review-doc
The parent orchestrates. It does not scan unless the host cannot spawn subagents — then it runs one worker at a time. Each check in Checks is one worker.
Work one page at a time. checks/ and logs/ are relative to this skill; docs/ is relative to the project root (docs.json at the root). Publisher-facing usage is in README.md.
Gotchas
- Do not invent pages, procedure steps, prerequisites, audience, or information architecture.
- Do not convert between equivalent docs.page forms (
<Info>↔ GitHub alerts;↔<Image>;<Property>↔ a short markdown table;<Tabs>/<TabItem>naming). - Do not apply a fix that would make the page worse.
- Do not auto-apply a held heading rewrite: an edit that changes a
##/###/#line (any check, not onlyheadings) to wording that slugifies to a different id. Slugify: lowercase, strip non-alphanumerics, spaces to hyphens (Set up iOS→set-up-ios; duplicates get-1,-2). Sentence case or a trailing period that keep the same id may apply. Leave the heading anddecision: null; the publisheraccepts it and renames the heading and the/page#sluglinks together. - If the live page already shows steps, callouts, tabs, cards, or images, re-fetch raw MDX — missing tags in converted HTML are not findings.
Loop
- Read
logs/<page-slug>.jsonif it exists (docs/index.mdx→docs--index.mdx.json). - Run checks. Merge findings. Write the log (pending
decision: nullis OK until they choose). - Print the Results as a user-visible message. If
failing > 0, list violations grouped under a heading per failing check. Do this after every run — including reruns under fix all, the stop run, and the cap run. The log is not a substitute. Do not skip, defer, or collapse runs into a final-only summary. Do not wait untilfailing == 0or the loop ends. - Default is fix all. Print this run first, then continue step 5. Do not wait for a mode choice. Review each only if they asked to review each, not apply, or decide one by one. If they already said fix all or auto-fix, same path as the default.
- Fix all: set every unmuted finding except a held heading rewrite to
accepted, apply, and continue this loop (step 7). If the only leftover unmuted findings are held heading rewrites, stop the auto-loop — do not rerun. Review each: wait. Publisher marksacceptedorrejectedby id (tone-1). Reject mutes that instance.mute check <id>mutes every instance of that check in either mode.unmute <id>reopens that instance.unmute check <id>reopens that check. Mute does not revert edits already written; the publisher reverts the file. - Apply only
acceptededits. Do not auto-apply a held heading rewrite. An explicitaccept <id>applies even when the slug changes. Do not edit completed runs. The only in-place update isdecision/feedbackwhile stillnull. - If they ask again, or fix all is still in progress, and
failing > 0for reasons other than held heading rewrites, rerun failing checks and any check whose text sits in the accepted-edit delta. Do not rerunpassingormutedon unchanged sentences. Then go to step 3 and print that run before applying or spawning another. - Stop when
failing == 0, or when the only remaining unmuted findings are held heading rewrites. Print the results; omit the violation list only whenfailing == 0. If they ask again, reprint that summary. - Cap at 3 runs. If still failing for reasons other than held heading rewrites, stop, print the results and leftover failing checks.
Publisher example
use review-doc on docs/index.mdx
review each
accept tone-1
reject links-2
mute check tone
unmute tone-1
unmute check tone
Run checks
Spawn one subagent per check in Checks, all in one parallel batch. On later runs, spawn only the checks from loop step 7. If the host cannot spawn subagents, run the same workers sequentially.
Each worker prompt (<skill> is this skill directory):
You are review-doc worker `<id>`.
Read the page <path> and <skill>/checks/<id>.md.
Do not edit. Do not read other checks. Do not write the log.
Obey Gotchas (no invented steps/audience/IA, no MDX conversion, no worse page, converted HTML is not a finding).
Finish every Scan on the whole page. Classify each instance: violation, skip, or clean.
Return JSON only:
{
"check": "<id>",
"scans": [{ "id": "<heading slug>", "status": "hit" | "clean" | "skip" }],
"findings": [{ "evidence": "<quote>", "recommendation": "<edit>" }]
}
`scans` must include every ### heading in checks/<id>.md.
A missing scan id, missing JSON, or wrong check is an orchestrator error: retry that worker once, then log the check as missing (not passing).
After merge, ignore worker-level pass/fail. Drop findings whose check + normalized evidence is already muted, or whose check was mute check <id>.
Group remaining findings whose evidence overlaps (same quote, or one quote contains the other).
- If the recommendations can both apply, keep both.
- If they cannot, do not log two independent accept/reject items. Emit one finding:
checkis the earlier id in Checks,conflictsis the other check ids,recommendationis a single edit that satisfies every check in the group. If no single edit works, say so inrecommendationand leavedecisionnull.
Assign stable ids <check>-1, <check>-2, … (counter per check, Checks order). Then set each check:
failing— one or more unmuted violations (a check named only inconflictsstill fails)passing— every Scan finished, zero violationsmuted— remaining violations are all muted; no unmuted failures
A missing check in the log means it was not scanned. Do not reopen muted instances unless the publisher asks.
Results
Print this as a user-visible message after every run, before applying edits or starting the next run. Print it first in that message. Monospace columns, no grid. Zero counts in the table are -. If the host colors text, failing is red, muted is yellow, passing is green.
A run that is not printed to the publisher is an orchestrator error. Fix-all already in the request, a planned later run, or an unchanged passing row is not a reason to hide this run's results.
> 16 checks · 2 failing · 1 muted · 13 passing docs/index.mdx
CHECK STATUS VIOLATIONS MUTED DESCRIPTION
person-and-voice passing - - you not we; one person; active voice
inline-formatting failing 1 - code font; UI bold; list shape
tone failing 1 - no idioms, padding, or pre-announcement
word-list muted - 1 please, e.g., utilize, simply, easy
One row per check in Checks order. Description is the one-liner in Checks, or the dominant violation.
Then violations for failing checks only, grouped under a ### <check> heading per check, in Checks order. Restart numbering under each heading. Do not list muted checks here.
## Violations
### inline-formatting
1. `inline-formatting-1` — <what to change>
Evidence: `<quote>`
Do this: <concrete edit>
### tone
1. `tone-1` — <what to change>
Evidence: `<quote>`
Do this: <concrete edit>
When conflicts is non-empty: `inline-formatting-1` (conflicts: `tone`). List the item under the finding's check (the earlier id).
A held heading rewrite still lists under Violations. Mark it held (accept headings-1 to apply; the new wording would change the #slug).
Log
Write logs/<page-slug>.json in loop step 2, before the print. Create { "skill": "review-doc", "page": "docs/index.mdx", "runs": [] } if needed. Append a run matching the field shape in logs/example.json. sourceRoot and projectRoot are .. Do not edit completed runs. The only in-place update is decision / feedback while still null.
Every live run must include summary and a checks array with every id in Checks. findings are the violation list (id is <check>-n; check is the check id; conflicts is an array of other check ids, [] when none). The example shows field shape, not a full check list.
Checks
Checks table order. Spawn one worker per file; read that file only when that worker runs.
- person-and-voice — you not we; one person; active voice
- procedures — numbered sequences; one action per step
- headings — frontmatter; sentence case; no
#in the body - inline-formatting — code font; UI bold; list shape
- links — descriptive text; root-relative in-site URLs
- tone — no idioms, padding, or pre-announcement
- general-principles — claims, jargon, inclusive language
- language — acronyms, tense, anthropomorphism
- sentence-structure — condition before the instruction
- punctuation — list stems, serial comma, dashes
- text-formatting — bold, italics,
& - formatting — callouts, dates, tables, figures
- computer-interfaces — fences, placeholders, commands
- names — product spelling, filenames, example hosts
- word-list — please, e.g., utilize, simply, easy
- accessibility-and-global — alt, position words, sentence length