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.
Phase 1: Get and Analyze Document
If a document path is provided: Read it, then proceed.
If no document is specified: Ask which document to review, or find the most recent in docs/brainstorms/ or docs/plans/ using a file-search/glob tool (e.g., Glob in Claude Code).
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 contains:
- User-facing features, user stories, or customer-focused language
- Market claims, competitive positioning, or business justification
- Scope decisions, prioritization language, or priority tiers with feature assignments
- Requirements with user/customer/business outcome focus
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
- Goals that don't clearly connect to requirements
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 flowBuild Agent List
Always include:
compound-engineering:document-review:coherence-reviewercompound-engineering:document-review:feasibility-reviewer
Add activated conditional personas:
compound-engineering:document-review:product-lens-reviewercompound-engineering:document-review:design-lens-reviewercompound-engineering:document-review:security-lens-reviewercompound-engineering:document-review:scope-guardian-reviewercompound-engineering:document-review:adversarial-document-reviewer
Dispatch
Dispatch all agents in parallel using the platform's task/agent tool (e.g., Agent tool in Claude Code, spawn in Codex). Each agent receives the prompt built from the subagent template included below with these variables filled:
| Variable | Value |
|---|---|
{persona_file} | Full content of the agent's markdown file |
{schema} | Content of the findings schema included below |
{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.
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 included below:
- 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")
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_typefrom 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(blocking risks surfaced as residual concerns are inherently about something the document failed to address).
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(contradictions are by definition about conflicting things the document says, not things it omits) - 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
| Autofix Class | Route |
|---|---|
auto | Apply automatically -- local deterministic fix (terminology, formatting, cross-references, completeness corrections where the correct value is verifiable from the document itself) |
batch_confirm | Group for single batch approval -- obvious fixes that touch meaning but have one clear correct answer |
present | Present individually for user judgment |
Demote any auto finding that lacks a suggested_fix to batch_confirm. Demote any batch_confirm finding that lacks a suggested_fix to present.
Completeness corrections eligible for auto: A finding qualifies when the correct fix is deterministically derivable from other content in the document. Examples: a count says "6 units" but the document lists 7, a summary omits an item that appears in the detailed list, a cross-reference points to a renamed section. If the fix requires judgment about *what* to add (not just *that* something is missing), it belongs in batch_confirm or present.
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 platform's edit tool
- Track what was changed for the "Auto-fixes Applied" section
- Do not ask for approval -- these are unambiguously correct
Batch Confirm
If any batch_confirm findings exist, present them as a group for a single approval:
- List the proposed fixes in a numbered table
- Use the platform's blocking question tool (AskUserQuestion in Claude Code, request_user_input in Codex, ask_user in Gemini) to ask: "Apply these N fixes? (yes/no/select)". If no blocking question tool is available, present the table with numbered options and wait for the user's reply before proceeding.
- If approved, apply all in a single pass
- If "select", let the user pick which to apply
- If rejected, demote remaining to the
presentfindings list
This turns N obvious-but-meaning-touching fixes into 1 interaction instead of N.
Present Remaining Findings
Present present findings using the review output template included below. Within each severity level, separate findings by type:
- Errors (design tensions, contradictions, incorrect statements) first -- these need resolution
- Omissions (missing steps, absent details, forgotten entries) second -- these need additions
Brief summary at the top: "Applied N auto-fixes. Batched M fixes for approval. 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
Use the platform's blocking question tool when available (AskUserQuestion in Claude Code, request_user_input in Codex, ask_user in Gemini). Otherwise present numbered options and wait for the user's reply.
Offer:
- Refine again -- another review pass
- Review complete -- document is ready
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 any of the 2 caller skills (ce-brainstorm, ce-plan)
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