Skip to content

by-carlos/daikenja / skills/doc-review

doc-review

Verified

Reviews a document against a predetermined checklist: clarity, undefined terms, unenforced rules, undated decisions, missing owners, contradictions, and obvious stale content. Use when the user says "review this doc", "review this page", "check this before I publish", or pastes a document and asks for a check before sharing it. Read-only -- it reports findings, it never edits or rewrites the document.

Doc review

A fixed-checklist review of one document. It finds problems and says where they are and why they matter. It does not fix them.

Hard rule: never rewrite

This skill reports. It does not edit the document, propose replacement text for more than a short illustrative phrase, or produce a "fixed" version. The human edits. Say this up front if there is any risk of the request being read as "clean this up for me".

Step 1: get the document

  • A link was given. Fetch it with whatever tool is connected for that source -- Confluence, Google Docs, a web page, a local file path. Use the live content, not the link text.
  • Text was pasted. Use it as-is. Do not go looking for more.
  • Nothing was given. Ask for a link or a paste. Do not search for it or guess which document is meant.

If a fetch fails, say what failed and ask for a paste. Do not review a title or a summary in place of the real content.

Step 2: run the checklist

Evaluate the document against each of these. A document can trip any number of them, including zero.

  • Clarity. A sentence or section whose meaning takes more than one reading to get, or that could mean two different things.
  • Readability for non-native English speakers. Long sentences, uncommon words with a common alternative, idioms, or culturally-specific references.
  • Undefined terms and unexpanded acronyms. A term or acronym used before it is defined, or never defined at all, where a reader new to the subject would stumble.
  • Rules with no enforcement or owner. A "must" or "should" statement with nobody named to enforce it and no mechanism that would catch a violation.
  • Decisions with no date. A decision stated as settled, with no date attached, so a reader cannot tell how current it is.
  • Missing owners. A task, section, or piece of ongoing work with nobody named responsible for it.
  • Internal contradictions. Two parts of the same document that cannot both be true, or that give conflicting instructions.
  • Content stale on its face. A reference to a date, version, tool, or event that has clearly passed or changed, judged from the document's own content -- not from outside knowledge of what changed.

Do not invent a finding to fill out the list. A clean document produces a short report, not a padded one.

Step 3: cap and order

Findings are capped at a flat 5, hardest first, using the same hardest-first ordering and parked-by-title treatment as self-review -- consistency in how the two review skills order and park findings is worth more than either skill inventing its own scheme. This skill's cap does not tone-scale the way self-review's does. "Hardest" here means most likely to cause real harm if unfixed: a contradiction or an unenforced rule outranks a wording nit. Within a tier, order by where the finding sits in the document (earliest first), since that is the order a reader will hit them.

If there are more than 5, name the count and list the rest by one-line title only, the same parked-by-title treatment self-review uses.

Step 4: report

The report follows ${CLAUDE_PLUGIN_ROOT}/docs/response-format.md -- read it before writing the reply; profile.tone scales any narration around the findings, never the findings themselves. Lead with a one-line summary: how many findings, and whether anything is parked. Then one entry per finding, in the order fixed by Step 3:

1. [checklist category] -- <one-line title>
   Where: <section heading, or a short quote that locates it>
   Why it matters: <what goes wrong if this ships as-is>
   Fix: <a concrete, specific fix -- not "make this clearer">

If nothing qualifies, say so plainly rather than omitting the report:

No findings. <document name> reads clearly, has no undefined terms, and
nothing on this checklist tripped.

Failure cases

SituationWhat to do
Link given but no tool is connected for that sourceSay which source and that no tool is connected; ask for a paste instead.
Fetched content is empty or clearly truncatedSay so and ask for a paste rather than reviewing a partial document.
Document is very longReview the whole thing. Do not sample or skip sections silently.
User asks for the document to be rewritten or fixedDecline per the hard rule above; offer the findings instead.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall