review-doc
Skill0 starsChanged 6 months agoMITView on GitHub
Semantic review of a single doc — classify each prose rule (enforced-by / tested-by / convention-only / unenforced / AMBIGUOUS) and emit BLOCKER / CHANGE-REQUEST / NIT / AMBIGUOUS findings. Dispatches the doc-reviewer agent. Use when reviewing an ADR / SPEC / AUDIT / README / PRD / SKILL.md / agent file before merge, or when the operator says "doc looks good", "ship this spec", "review this doc", "is this doc accurate", "check this spec", "look at this doc", "verify this doc". For multi-doc fan-out (e.g., "review every doc"), use `/audit-docs-semantic` instead — that one is operator-only with a $5 cap.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- angadhn/botferencetheir own version, first seen Nov 13, 2026
- koruworks/skillstheir own version, first seen Oct 15, 2026
- Endava/BEEQtheir own version, first seen Oct 8, 2026
- kohj1018/agentic-dev-harnesstheir own version, first seen Sep 29, 2026
- mekenthompson/ProductOStheir own version, first seen Jul 23, 2026
- tomharris/engineer-agenttheir own version, first seen Jul 22, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- Endava/BEEQ★ 162same name
- DGouron/review-flow★ 44same name
- angadhn/botference★ 20same name
- kohj1018/agentic-dev-harness★ 2same name
- mekenthompson/ProductOS★ 1same name
- koruworks/skills★ 0same name
- tomharris/engineer-agent★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- audit-docs-semanticSkill
- audit-docsSkill
- audit-harness-coverageSkill
- budget-statusSkill
- cavemanSkill
- configurationSkill
- critic-reviewSkill
- doc-patternSkill
- error-taxonomySkill
- grill-meSkill
- grill-with-docsSkill
- new-docSkill
- python-failure-modesSkill
- review-changesSkill
- rust-failure-modesSkill
- verification-before-completionSkill
- zoom-outSkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
If the operator's intent is "scan everything for structural drift," route to /audit-docs.
- Distinctive: line 36
No match → load no appendix.
- Very specific: line 38
Choose the model: Default: Sonnet (claude-sonnet-4-6).
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/review-doc
Semantic review of a single doc, complementary to /audit-docs (deterministic structural). This skill dispatches the doc-reviewer agent to read the dispatched doc end-to-end, classify every prose rule against a base prompt + path appendix, and emit a verdict with cited evidence.
This skill is operator-invocable AND auto-loadable — typing /review-doc <path> works, and the description-match auto-trigger fires when the operator types intent like "doc looks good", "ship this spec", "review this doc". The auto-trigger is a soft-trigger: it is a suggestion mechanism gated on operator-typed intent, not an autonomous loop. Operator opt-out: flip disable-model-invocation: true in this file's frontmatter to make /review-doc slash-only.
Scope vs /audit-docs
/audit-docs | /review-doc (this skill) | |
| Surface | docs/, CLAUDE.md, .claude/{skills,agents,rules,hooks} (all docs) | One dispatched doc |
| Method | D1–D11 (deterministic only) for upstream /audit-docs, semantic review here | Sonnet (default) / Opus (safety-critical paths), full doc read |
| Catches | Index gaps, dead links, frontmatter, citations, ADR id density, staleness | Prose-rule classification, internal contradictions, missing required sections, unenforced claims |
| Cost | $0 (deterministic only) | ~$0.08 (Sonnet) / ~$0.40 (Opus) per doc |
| Output | .claude/audits/<date>-docs-audit.md | Inline verdict in current session (cached for re-dispatch) |
If the operator's intent is "scan everything for structural drift," route to /audit-docs. If the intent is "did I write this SPEC's prose carefully enough," route here.
When invoked: /review-doc <doc-path>
- Validate the path. Resolve
<doc-path>against the repo. If it does not exist or is not a markdown file, list the closest matches and stop. - Read the doc's frontmatter
type:and full relative path. These select the base prompt and path appendix:- Base prompt —
.claude/skills/review-doc/prompts/<type>.mdfortype ∈ {ADR, SPEC, AUDIT, README, PRD}. Fortype ∈ {RFC, TDD, POSTMORTEM}(currently 0 instances each), fall back toprompts/cross-cutting.mdand emit a NIT noting the type-specific prompt is missing. - Path appendix — chosen by path heuristic:
docs/harness/components/**(ordocs/components/**in forks with a flatter layout) →prompts/appendix-components.md.claude/skills/**or.claude/agents/**→prompts/appendix-skill-shape.md.claude/rules/**→prompts/appendix-rules-catalog.md- Multiple matches → load both; let the agent reconcile.
- No match → load no appendix; the base prompt covers it.
- Base prompt —
- Choose the model. Default: Sonnet (
claude-sonnet-4-6). Override to Opus (claude-opus-4-7) when the dispatched path matches a safety-critical SPEC the project has declared (configure the list in this skill's project config). Setmodel_override: claude-opus-4-7on the agent dispatch for those paths. - Dispatch the
doc-revieweragent. Pass:- The doc path.
- The base-prompt path and appendix path(s).
model_override(if applicable).- The cache directory hint (
var/<env>/review-cache/).
- Surface the verdict to the operator: PASS / CHANGE-REQUEST / BLOCK + counts of blockers / change-requests / nits / ambiguous + the cited
RESULT:JSON line. Do not auto-create issues. Do not auto-edit the doc. - Cache write is the agent's responsibility (see
doc-reviewer.md<Cache>section). If the cache write fails, the operator sees a warning but the verdict still lands.
Status
Live. The agent + skill + prompt templates are present:
prompts/{ADR,SPEC,AUDIT,README,PRD,cross-cutting}.mdprompts/appendix-{components,skill-shape,rules-catalog}.md
Dispatching /review-doc <path> proceeds end-to-end. A failed prompt load is a hard error (missing prompt → re-add the template), not an expected stub state.
Rules
- One doc per dispatch. N-doc fan-out is
/audit-docs-semantic(PR-C). If the operator passes a directory, refuse and route to that skill. - Read-only. The agent's
disallowedToolsenforces no Write / Edit / NotebookEdit. - No auto-issue creation. Findings stay in-session; the operator decides what to escalate (P5 — Outalator-shape).
- Honour the model tier. Sonnet by default (recoverable consequence — operator overrides verdict). Opus only on the listed safety-critical paths. Do not promote to Opus on operator hunch; document the path-list amendment first.
Forbidden
- Dispatching against multiple docs in one invocation.
- Running the agent without first selecting the right base prompt + path appendix.
- Auto-creating GitHub Issues from findings.
- Modifying the dispatched doc in any way.
- Promoting to Opus outside the listed safety-critical path set without an audit amendment.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

