// Review requirements or plan documents using parallel persona agents that surface role-specific issues. Use when a requirements document or plan document exists and the user wants to improve it, or when invoked by /cplan for quality gating.
| name | document-review |
| description | Review requirements or plan documents using parallel persona agents that surface role-specific issues. Use when a requirements document or plan document exists and the user wants to improve it, or when invoked by /cplan for quality gating. |
| argument-hint | [mode:headless] [path/to/document.md] |
Review requirements or plan documents through multi-persona analysis. Dispatches specialized reviewer agents in parallel, auto-fixes quality issues, and presents strategic questions for user decision.
Read these on-demand at the step that needs them — do not bulk-load at start:
references/subagent-template.md — prompt template for dispatching persona agents (read at Phase 2)references/findings-schema.json — JSON schema reviewers must conform to (read at Phase 2, pass to reviewers)references/review-output-template.md — output format for presenting synthesized findings (read at Phase 4)Check the skill arguments for mode:headless. Arguments may contain a document path, mode:headless, or both. Tokens starting with mode: are flags, not file paths -- strip them from the arguments and use the remaining token (if any) as the document path for Phase 1.
If mode:headless is present, set headless mode for the rest of the workflow.
Headless mode changes the interaction model, not the classification boundaries. Document-review still applies the same judgment about what has one clear correct fix vs. what needs user judgment. The only difference is how non-auto findings are delivered:
auto fixes are applied silently (same as interactive)present findings are returned as structured text for the caller to handle -- no #askQuestions prompts, no interactive approvalThe caller receives findings with their original classifications intact and decides what to do with them.
If mode:headless is not present, the skill runs in its default interactive mode with no behavior change.
If a document path is provided: Read it, then proceed.
If no document is specified (interactive mode): Ask which document to review using #askQuestions, or find the most recent in docs/brainstorms/ or docs/plans/ using Glob.
If no document is specified (headless mode): Output "Review failed: headless mode requires a document path. Re-invoke with: /document-review mode:headless <path>" without dispatching agents.
After reading, classify the document:
docs/brainstorms/, focuses on what to build and whydocs/plans/, focuses on how to build it with implementation detailsAnalyze the document content to determine which conditional personas to activate. Check for these signals:
product-lens -- activate when the document makes challengeable claims about what to build and why, or when the proposed work carries strategic weight beyond the immediate problem. Check for either leg:
Leg 1 — Premise claims: The document stakes a position on what to build or why that a knowledgeable stakeholder could reasonably challenge:
Leg 2 — Strategic weight: The proposed work could affect system trajectory, user perception, or competitive positioning:
design-lens -- activate when the document contains:
security-lens -- activate when the document contains:
scope-guardian -- activate when the document contains:
adversarial -- activate when the document contains:
Tell the user which personas will review and why. For conditional personas, include the justification:
Reviewing with:
- coherence-reviewer (always-on)
- feasibility-reviewer (always-on)
- scope-guardian-reviewer -- plan has 12 requirements across 3 priority levels
- security-lens-reviewer -- plan adds API endpoints with auth flow
Always include:
coherence-reviewerfeasibility-reviewerAdd activated conditional personas:
product-lens-reviewerdesign-lens-reviewersecurity-lens-reviewerscope-guardian-revieweradversarial-document-reviewerRead references/subagent-template.md and references/findings-schema.json to build the prompt.
Dispatch all agents in parallel using the Agent tool. Each agent receives the prompt built from the subagent template with these variables filled:
| Variable | Value |
|---|---|
{persona_file} | Full content of the agent's markdown file |
{schema} | Content of the findings schema |
{document_type} | "requirements" or "plan" from Phase 1 classification |
{document_path} | Path to the document |
{document_content} | Full text of the document |
Pass each agent the full document -- do not split into sections.
Error handling: If an agent fails or times out, proceed with findings from agents that completed. Note the failed agent in the Coverage section. Do not block the entire review on a single agent failure.
Dispatch limit: Even at maximum (7 agents), use parallel dispatch. These are document reviewers with bounded scope reading a single document -- parallel is safe and fast.
Process findings from all agents through this pipeline. Order matters -- each step depends on the previous.
Check each agent's returned JSON against the findings schema:
Suppress findings below 0.50 confidence. Store them as residual concerns for potential promotion in step 3.4.
Fingerprint each finding using normalize(section) + normalize(title). Normalization: lowercase, strip punctuation, collapse whitespace.
When fingerprints match across personas:
Findings = Auto + Present stays exact.Scan the residual concerns (findings suppressed in 3.2) for:
finding_type from the corroborating above-threshold finding.finding_type: omission.When personas disagree on the same section:
autofix_class: presentfinding_type: errorSpecific conflict patterns:
Severity and autofix_class are independent. A P1 finding can be auto if the correct fix is obvious.
| Autofix Class | Route |
|---|---|
auto | Apply automatically -- one clear correct fix |
present | Present individually for user judgment |
Demote any auto finding that lacks a suggested_fix to present.
Auto-eligible patterns: summary/detail mismatch (body is authoritative over overview), wrong counts, missing list entries derivable from elsewhere in the document, stale internal cross-references, terminology drift, prose/diagram contradictions where prose is more detailed, missing steps mechanically implied by other content, unstated thresholds implied by surrounding context, completeness gaps where the correct addition is obvious.
Sort findings for presentation: P0 -> P1 -> P2 -> P3, then by finding type (errors before omissions), then by confidence (descending), then by document order (section position).
Apply all auto findings to the document in a single pass:
List every auto-fix in the output summary so the user can see what changed.
Headless mode: Do not use #askQuestions. Output all non-auto findings as structured text:
Document review complete (headless mode).
Applied N auto-fixes:
- <section>: <what was changed> (<reviewer>)
Findings (requires judgment):
[P0] Section: <section> — <title> (<reviewer>, confidence <N>)
Why: <why_it_matters>
Suggested fix: <suggested_fix or "none">
Residual concerns:
- <concern> (<source>)
Deferred questions:
- <question> (<source>)
Omit any section with zero items. Then proceed directly to Phase 5.
Interactive mode:
Read references/review-output-template.md for the exact output format.
Present present findings using the review output template. Within each severity level, separate findings by type:
Brief summary at the top: "Applied N auto-fixes. K findings to consider (X errors, Y omissions)."
Include the Coverage table, auto-fixes applied, residual concerns, and deferred questions.
During synthesis, discard any finding that recommends deleting or removing files in:
docs/brainstorms/docs/plans/docs/solutions/These are pipeline artifacts and must not be flagged for removal.
Headless mode: Return "Review complete" immediately. Do not ask questions.
Interactive mode:
Use #askQuestions to offer these options. Use the document type from Phase 1 to set the "Review complete" description:
/cplan"/work"After 2 refinement passes, recommend completion -- diminishing returns are likely. But if the user wants to continue, allow it.
Return "Review complete" as the terminal signal for callers.
/brainstorm, /cplan, or external skills that invoke /document-review)On subsequent passes, re-dispatch personas and re-synthesize. The auto-fix mechanism and confidence gating prevent the same findings from recurring once fixed. If findings are repetitive across passes, recommend completion.
@./references/subagent-template.md
@./references/findings-schema.json
@./references/review-output-template.md
Explore requirements and approaches through collaborative dialogue before writing a right-sized requirements document and planning implementation. Use for feature ideas, problem framing, when the user says 'let's brainstorm', or when they want to think through options before deciding what to build.
Document a solved problem as reusable institutional knowledge with parallel research. Use when the user says 'document this', 'compound', 'save learnings', or wants to capture a solution for future reference.
Research the codebase and create a structured implementation plan. Use when the user says 'plan this', 'create a plan', 'how should we implement', or wants to turn a feature description into a structured implementation plan.
Scaffold a new custom agent — reviewers, researchers, or workflow agents. Use when asked to create, scaffold, or add a new agent.
Enhance an existing plan with parallel research agents for depth, best practices, and implementation details. Use when the user says 'deepen the plan', 'research more', or when a plan has high-risk dimensions that need more investigation.
Commit, push, and open a PR with an adaptive, value-first description. Use when the user says "commit and PR", "push and open a PR", "ship this", "create a PR", "open a pull request", or wants to go from working changes to an open pull request in one step. Also handles "update the PR description" or "refresh the PR description".