Doc Review

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