Doc Review: Claude Code skill for reviewing design docs

Doc Review is a Claude Code skill, built at AR Labs, that audits a planning document before anyone builds from it, using reviewers from a different model family than the one that usually writes the document. Several reviewers read the document in parallel, each against one concern, and their findings are filtered, merged and presented to the author to accept or reject. If the author asks for a redraft, a final reader with no context at all checks whether the new version can be followed. We run it on PRPs (product requirement prompts: plans agents build from, in Rasmus Widing's format, adapted), design documents, architecture decision records, design briefs and implementation specs (written specifications for one task: what to build and how each criterion is proved), and on any other document where the only question is whether a stranger could follow it. Its methodology checklist is our distillation of Matt Pocock's teaching on planning work for AI agents.

How it works

Detect the type. The filename decides first, then the headings. A recognised planning document gets all four review axes. Anything else, a README or a working note, gets the readability axis alone, and the report says so at the top so a one-axis run never reads as a full review. An architecture decision record takes a cheaper single-pass route.

Deterministic checks. Before any model reviews anything, the orchestrating session checks required sections, file references that should resolve, valid status values and dates that are not in the future. Missing required sections or a missing rubric stop the run. A broken link or an odd date does not; it becomes a finding.

Four specialists, in parallel. Each runs as a separate pass of OpenAI's Codex CLI, a different model family from the one that usually wrote the document, so the reviewer does not share the author's blind spots. Each pass starts in an empty working folder, because Codex otherwise loads the repository's own agent instructions and would arrive already holding the context the document is supposed to supply. If Codex fails for any reason, the skill falls back to Claude reviewers and says in the report that the independence is weaker.

• Principles: separation of concerns, a single source of truth for each fact, technology-free goals, decision-record format, the quality of the acceptance criteria. For implementation specs this reviewer also spot-checks every claim the spec makes about existing code against the code itself.
• Methodology: seventeen yes-or-no checks drawn from Matt Pocock's teaching (vertical slices, deep modules, test-first implementation, fresh-context review and others), plus four of our own. For specs, this axis is replaced by a check of the spec's quality gates, read from the gate list at review time rather than copied, so the two cannot drift apart.
• Consistency: loads every linked document and looks for contradictions, scope drift and broken references.
• Readability: reads only the document and the rubric, never the files it references.

Refutation, then meta-review. A fresh pass tries to refute the principles, methodology and consistency findings; a finding nobody could confirm by reading the cited section cannot stay above the lowest severity. The orchestrator then merges duplicates, resolves severity conflicts and caps the findings that reach the author at ten, keeping only what would change a decision. Readability findings with their instance lists are shown in full outside that cap.

The author decides. Each finding is marked fix, acknowledge, or not actionable. Only then is a redraft offered.

The judgement it encodes

The readability reviewer's ignorance is the instrument. The question is whether a reader without the author's context can follow the document. A reviewer that opens the referenced files acquires that context and can no longer notice its absence.

Readability findings are not sent to refutation. A refuter has to read the document closely and completely, which is exactly how it gains the context the first-time reader lacked. It then answers an easier question, "is this term introduced somewhere?", instead of the real one, "would this reader follow it?". A false alarm on readability costs one extra clause; a missed problem ships an unreadable document with a clean review attached. The right check for a readability finding is to reproduce it with a cold reader, not to argue with it.

Never trim an instance list. The finding cap limits how many findings reach the author, never how many instances one finding lists. A criterion that fails in nine places lists all nine, by term and section.

Redraft by addition, and only three moves. Introduce each referent before it is referred to, define each unfamiliar term at first use, and open each decision-carrying section with a plain-English line. The redraft changes no claim, drops no qualifier and keeps tables as tables. Any other change is listed separately as a judgement call.

The redrafter cannot check its own grounding. Every redraft goes to a reader with no prior context, which answers three questions from the text alone: what the document is for, what each named term means ("not stated" where the document never says), and what it would do first. Its answers are shown to the author verbatim before anyone interprets them. If the cold reader cannot find something because the document never contained it, that is reported as a content gap for the author to fill, not invented by the redraft.

What exists today

We use the skill regularly on our planning documents and specs. Its output is advisory: it records no verdict and blocks nothing in the pipeline. It keeps no readability rules of its own and reads them from the Write Well skill's rubric, so the two cannot disagree. Our research on what makes one model a useful reviewer of another is in using one LLM to review another.

Example

Illustrative example. A run on a design document might report:

## /doc-review Results: notifications DESIGN.md
 
Routing: DESIGN.md (filename)
Axes run: principles, methodology, consistency, readability
Summary: 1 CRITICAL, 2 WARNING, 6 NOTEs (summarised below)
 
1. CRITICAL: Goals name a technology
Section: 2. Goals and Non-Goals
Axis: principles
Finding: Goal G2 commits to WebSockets, which is a design choice,
not a goal.
Suggested fix: State the user-visible outcome; move the transport
choice to System Design with its own decision record.
Confidence: high
 
2. WARNING: R1 Grounding: presupposed context
Axis: readability
Instances (3):
| Item               | Section          | First use                      |
|--------------------|------------------|--------------------------------|
| "the fan-out seam" | 4. System Design | "the fan-out seam owns retries" |
| "the backfill job" | 4.2 Storage      | "until the backfill job runs"   |
| "Q3 cutover"       | 6. Rollout       | "after the Q3 cutover"          |