| name | document-review |
| description | Multi-persona review of a planning artifact (coherence/feasibility/scope/adversarial) -> P0-P3 findings before lock. Use to review a task card, wave plan, or spec, or /document-review. |
Document Review
You review planning artifacts before they lock. Where wave-review reviews execution output, you review
documents — task cards, wave plans, requirements, specs. You surface gaps, contradictions, and unstated
assumptions before they become execution errors. Domain-neutral: the artifact may describe software, a
finance model, or a curriculum; the reviewer lenses apply to all.
What this does / does not do
Does: classify the document, spawn 4–5 parallel reviewer sub-agents (each read-only), synthesize their
findings via grader, write a receipt, and return a consolidated P0–P3 finding report. Does not:
edit the document (it surfaces what needs fixing), review code diffs (wave-review), or lock the document.
When NOT to use
- The target is a code change / diff — use wave-review; document-review is for planning artifacts only.
- A document-review receipt already exists for this exact document version — re-review adds cost with no
new signal.
Reference Routing
| Situation | Reference |
|---|
| The 5 reviewer role prompts + the document-type → reviewer-set table | references/reviewer-prompts.md |
| Finding synthesis | the grader module |
| Receipt write delegation | engine/shared/references/script-delegation-contract.md |
Inputs
| Field | Required | Description |
|---|
document_path | yes | the artifact to review |
document_type | no | task-card / wave-plan / requirements / spec (auto-detected from content) |
focus | no | a concern to emphasize (e.g. feasibility, scope) |
How to do it
Step 1 — Load and classify
Read the document. Detect type from content signals (task-card: goal: + complexity:; wave-plan:
## Waves + rollback_to:; requirements: ## Requirements + ## Success Criteria; spec: GWT
acceptance criteria). Auto-select the reviewer set for that type (references/reviewer-prompts.md).
Step 2 — Spawn reviewers in parallel
Send all selected reviewers in one response turn. Each receives the full document text + its role
prompt; each is read-only and returns findings in the standard form (severity, location, issue, fix,
confidence). Severity scale: P0 blocks locking (execution will fail/produce wrong results as
written) · P1 high-impact gap (likely REVISE loop) · P2 moderate (edge case, ambiguity) · P3
low-impact, advisory.
Step 3 — Synthesize via grader
Pass all reviewer outputs to grader (primary_output = combined findings; adversary_counter_analysis
= the adversarial-document findings; spec_artifact = the document). Grader returns ACCEPT (no P0/P1),
REVISE (P1 present), or ESCALATE (P0 present). Deduplicate identical location+title findings; when ≥2
reviewers surface the same issue, note the agreement and boost confidence by 0.10 (cap 1.0).
Step 4 — Write the receipt, then route
ACCEPT → report P2/P3 briefly; caller may lock. REVISE → present P0/P1 with fix actions; caller
addresses them or proceeds with explicit acknowledgment. ESCALATE → present P0 prominently; do not lock
until resolved; route coherence/feasibility P0 back to specify/decompose, scope P0 back to scope-frame.
Headless mode (invoked by another module, no user present): skip interactive prompts; return the
structured finding list; end with "Review complete".
Output Contract
document-review receipt (<workspace>/receipts/document-review-<timestamp>.json): base + target
(document path), verdict (ACCEPT|REVISE|ESCALATE), findings_p0/p1/p2/p3 (counts),
reviewers_spawned (list). persistence: Spec-Anchored.
Proactive Triggers
- A reviewer flags style ("could be clearer") as a finding: not a finding — drop it; only execution-risk
gaps count.
- Every gap rated P0: severity inflation — a missing example is P3, a contradictory acceptance
criterion is P0; calibrate to actual execution risk.
- The target is a diff, not a plan: wrong module — route to wave-review.
- Two reviewers surface the same issue: note the cross-reviewer agreement and boost confidence — convergence is signal.
- Blocking the lock on a P2/P3: P2/P3 are advisory; only P0 hard-blocks, P1 should-block with acknowledgment.
Completion Criteria
Done when: a document-review receipt is written with a verdict and P0–P3 counts; findings were
returned to the caller (or surfaced headlessly).
Not done if: document-review edited the document; it ran on a code diff; it blocked a lock on P2/P3.
Next step: the caller locks (ACCEPT), revises (REVISE), or resolves P0s (ESCALATE).
Related Skills
- specify / decompose: Invoke document-review on the card / wave plan before locking. NOT reviewers themselves.
- wave-review: Reviews code diffs after execution. NOT for planning artifacts — that is document-review.
- grader: Synthesizes document-review's reviewer findings into a verdict. NOT a reviewer spawner itself.