review-doc

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; ![alt](src) ↔ <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 only headings) 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 and decision: null; the publisher accepts it and renames the heading and the /page#slug links 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

1. Read logs/<page-slug>.json if it exists (docs/index.mdx → docs--index.mdx.json).
2. Run checks. Merge findings. Write the log (pending decision: null is OK until they choose).
3. 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 until failing == 0 or the loop ends.
4. 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.
5. 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 marks accepted or rejected by 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.
6. Apply only accepted edits. Do not auto-apply a held heading rewrite. An explicit accept <id> applies even when the slug changes. Do not edit completed runs. The only in-place update is decision / feedback while still null.
7. If they ask again, or fix all is still in progress, and failing > 0 for reasons other than held heading rewrites, rerun failing checks and any check whose text sits in the accepted-edit delta. Do not rerun passing or muted on unchanged sentences. Then go to step 3 and print that run before applying or spawning another.
8. Stop when failing == 0, or when the only remaining unmuted findings are held heading rewrites. Print the results; omit the violation list only when failing == 0. If they ask again, reprint that summary.
9. Cap at 3 runs. If still failing for reasons other than held heading rewrites, stop, print the results and leftover failing checks.