Document Review

Document Review

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.

Support Files

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)

Phase 0: Detect Mode

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 approval
• Phase 5 returns immediately with "Review complete" (no refine/complete question)

The 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.

Phase 1: Get and Analyze Document

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.

Classify Document Type

After reading, classify the document:

• requirements -- from docs/brainstorms/, focuses on what to build and why
• plan -- from docs/plans/, focuses on how to build it with implementation details

Select Conditional Personas

Analyze 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:

• Problem framing where the stated need is non-obvious or debatable
• Solution selection where alternatives plausibly exist
• Prioritization decisions that explicitly rank what gets built vs deferred
• Goal statements that predict specific user outcomes

Leg 2 — Strategic weight: The proposed work could affect system trajectory, user perception, or competitive positioning:

• Changes that shape how the system is perceived or what it becomes known for
• Complexity or simplicity bets that affect adoption, onboarding, or cognitive load
• Work that opens or closes future directions (path dependencies, architectural commitments)
• Opportunity cost implications

design-lens -- activate when the document contains:

• UI/UX references, frontend components, or visual design language
• User flows, wireframes, screen/page/view mentions
• Interaction descriptions (forms, buttons, navigation, modals)
• References to responsive behavior or accessibility

security-lens -- activate when the document contains:

• Auth/authorization mentions, login flows, session management
• API endpoints exposed to external clients
• Data handling, PII, payments, tokens, credentials, encryption
• Third-party integrations with trust boundary implications

scope-guardian -- activate when the document contains:

• Multiple priority tiers (P0/P1/P2, must-have/should-have/nice-to-have)
• Large requirement count (>8 distinct requirements or implementation units)
• Stretch goals, nice-to-haves, or "future work" sections
• Scope boundary language that seems misaligned with stated goals

adversarial -- activate when the document contains:

• More than 5 distinct requirements or implementation units
• Explicit architectural or scope decisions with stated rationale
• High-stakes domains (auth, payments, data migrations, external integrations)
• Proposals of new abstractions, frameworks, or significant architectural patterns

Phase 2: Announce and Dispatch Personas

Announce the Review Team

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

Build Agent List

Always include:

• coherence-reviewer
• feasibility-reviewer

Add activated conditional personas:

• product-lens-reviewer
• design-lens-reviewer
• security-lens-reviewer
• scope-guardian-reviewer
• adversarial-document-reviewer

Dispatch

Read 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:

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.

Phase 3: Synthesize Findings

Process findings from all agents through this pipeline. Order matters -- each step depends on the previous.

3.1 Validate

Check each agent's returned JSON against the findings schema:

• Drop findings missing any required field defined in the schema
• Drop findings with invalid enum values
• Note the agent name for any malformed output in the Coverage section

3.2 Confidence Gate

Suppress findings below 0.50 confidence. Store them as residual concerns for potential promotion in step 3.4.

3.3 Deduplicate

Fingerprint each finding using normalize(section) + normalize(title). Normalization: lowercase, strip punctuation, collapse whitespace.

When fingerprints match across personas:

• If the findings recommend opposing actions (e.g., one says cut, the other says keep), do not merge -- preserve both for contradiction resolution in 3.5
• Otherwise merge: keep the highest severity, keep the highest confidence, union all evidence arrays, note all agreeing reviewers (e.g., "coherence, feasibility")
• Coverage attribution: Attribute the merged finding to the persona with the highest confidence. Decrement the losing persona's Findings count and the corresponding route bucket (Auto or Present) so Findings = Auto + Present stays exact.

3.4 Promote Residual Concerns

Scan the residual concerns (findings suppressed in 3.2) for:

• Cross-persona corroboration: A residual concern from Persona A overlaps with an above-threshold finding from Persona B. Promote at P2 with confidence 0.55-0.65. Inherit finding_type from the corroborating above-threshold finding.
• Concrete blocking risks: A residual concern describes a specific, concrete risk that would block implementation. Promote at P2 with confidence 0.55. Set finding_type: omission.

3.5 Resolve Contradictions

When personas disagree on the same section:

• Create a combined finding presenting both perspectives
• Set autofix_class: present
• Set finding_type: error
• Frame as a tradeoff, not a verdict

Specific conflict patterns:

• Coherence says "keep for consistency" + scope-guardian says "cut for simplicity" -> combined finding, let user decide
• Feasibility says "this is impossible" + product-lens says "this is essential" -> P1 finding framed as a tradeoff
• Multiple personas flag the same issue -> merge into single finding, note consensus, increase confidence

3.6 Route by Autofix Class

Severity and autofix_class are independent. A P1 finding can be auto if the correct fix is obvious.

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.

3.7 Sort

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).

Phase 4: Apply and Present

Apply Auto-fixes

Apply all auto findings to the document in a single pass:

• Edit the document inline using the Edit tool
• Track what was changed for the "Auto-fixes Applied" section
• Do not ask for approval -- these have one clear correct fix

List every auto-fix in the output summary so the user can see what changed.

Present Remaining Findings

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:

• Errors first -- these need resolution
• Omissions second -- these need additions

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.

Protected Artifacts

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.

Phase 5: Next Action

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:

1. Refine again -- Address the findings above, then re-review
2. Review complete -- description based on document type:
   • requirements document: "Create technical plan with /cplan"
   • plan document: "Implement with /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.

What NOT to Do

• Do not rewrite the entire document
• Do not add new sections or requirements the user didn't discuss
• Do not over-engineer or add complexity
• Do not create separate review files or add metadata sections
• Do not modify caller skills (/brainstorm, /cplan, or external skills that invoke /document-review)

Iteration Guidance

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.

Included References

Subagent Template

@./references/subagent-template.md

Findings Schema

@./references/findings-schema.json

Review Output Template

@./references/review-output-template.md