Document Review

Interactive mode rules

• Pre-load the platform question tool before any question fires. In Claude Code, AskUserQuestion is a deferred tool — its schema is not available at session start. At the start of Interactive-mode work (before the routing question, per-finding walk-through questions, bulk-preview Proceed/Cancel, and Phase 5 terminal question), call ToolSearch with query select:AskUserQuestion to load the schema. Load it once, eagerly, at the top of the Interactive flow — do not wait for the first question site. On Codex, Gemini, and Pi this preload is not required.
• The numbered-list fallback applies only when the harness genuinely lacks a blocking question tool — ToolSearch returns no match, the tool call explicitly fails, or the runtime mode does not expose it (e.g., Codex edit modes where request_user_input is unavailable). A pending schema load is not a fallback trigger; call ToolSearch first per the pre-load rule. In genuine-fallback cases, present options as a numbered list and wait for the user's reply — never silently skip the question. Rendering a question as narrative text because the tool feels inconvenient, because the model is in report-formatting mode, or because the instruction was buried in a long skill is a bug. A question that calls for a user decision must either fire the tool or fall back loudly.

Phase 0: Detect Mode

• safe_auto fixes are applied silently (same as interactive)
• gated_auto, manual, and FYI findings are returned as structured text for the caller to handle — no blocking-question prompts, no interactive routing
• Phase 5 returns immediately with "Review complete" (no routing question, no terminal question)

Phase 1: Get and Analyze Document

Classify Document Type

• artifact_contract: ce-unified-plan/v1 plus artifact_readiness: requirements-only -> classify as unified-requirements. Review the Product Contract only; the absence of Planning Contract, Implementation Units, Verification Contract, or Definition of Done is expected and must not be flagged.
• artifact_contract: ce-unified-plan/v1 plus artifact_readiness: implementation-ready -> classify as unified-plan. Review Product Contract and Planning Contract with different lenses, then review Implementation Units/Verification/DoD for execution completeness.
• HTML unified artifacts (.html) are read/reviewed in report-only mode. Do not apply markdown mutation paths to HTML. If a caller requested mutation/autofix behavior, skip with the existing markdown-only message or return report-only findings.
• Invalid progress-like readiness values (active, in_progress, completed, done) are a document-contract finding, not an execution state to honor.

• Frontmatter fields like actors:, flows:, acceptance_examples:, or status: carrying brainstorm-shaped values
• Section headings such as Acceptance Examples, Actors, Key Flows, User Flows, Outstanding Questions, Resolve Before Planning
• Numbered identifiers in the form R1, R2, A1, F1, AE1 — requirement, actor, flow, and acceptance-example IDs
• Prose framing focused on user/business problem, behavior, scope boundaries, success criteria
• No implementation units, no per-unit file lists, no test scenarios attached to units

• Frontmatter fields like type: feat|fix|refactor, origin: docs/brainstorms/..., or product_contract_source: ce-brainstorm|ce-plan-bootstrap|legacy-requirements
• Section headings such as Implementation Units, Output Structure, Key Technical Decisions, Risks & Dependencies, System-Wide Impact
• Numbered identifiers in the form U1, U2 — implementation unit IDs
• Per-unit fields named Goal, Files, Approach, Test scenarios, Verification
• Repo-relative file paths to create/modify/test
• Prose framing focused on technical decisions, sequencing, and implementer-facing detail

Select Conditional Personas

• Problem framing where the stated need is non-obvious or debatable, not self-evident from existing context
• Solution selection where alternatives plausibly exist (implicit or explicit)
• Prioritization decisions that explicitly rank what gets built vs deferred
• Goal statements that predict specific user outcomes, not just restate constraints or describe deliverables

• 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 -- building this means not building something else

• 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

• 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

• 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

• The document is a requirements document with 2+ challengeable claims (problem framing, solution selection, prioritization, predicted outcomes) -- premise scrutiny is core to the brainstorm phase
• The document touches a high-stakes domain -- auth, payments, billing, data migrations, privacy/compliance, external integrations, cryptography -- regardless of doc type or size
• The document proposes a new abstraction, framework, or significant architectural pattern -- regardless of doc type
• The document is a plan with no validated upstream Product Contract signal (no legacy origin: requirements doc and no product_contract_source: ce-brainstorm or legacy-requirements) -- premise wasn't validated upstream
• The document is a plan that explicitly extends scope beyond its origin requirements doc (new actors, new flows, deferred-then-restored features)
• The document contains an explicit alternatives section or unresolved tradeoffs -- adversarial helps stress-test the chosen direction

Phase 2: Announce and Dispatch Personas

Announce the Review Team

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

• coherence-reviewer
• feasibility-reviewer

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

Dispatch

• coherence-reviewer: cheapest capable extraction/reasoning tier.
• design-lens-reviewer, security-lens-reviewer, scope-guardian-reviewer: platform mid-tier model.
• feasibility-reviewer, product-lens-reviewer, adversarial-document-reviewer: inherit the parent model unless the harness has an established high-capability review tier.

Decision primer

<prior-decisions>
Round 1 — no prior decisions.
</prior-decisions>

<prior-decisions>
Round 1 — applied (N entries):
- {section}: "{title}" ({reviewer}, {confidence})
  Evidence: "{evidence_snippet}"

Round 1 — rejected (M entries):
- {section}: "{title}" — Skipped because {reason}
  Evidence: "{evidence_snippet}"
- {section}: "{title}" — Deferred to Open Questions because {reason or "no reason provided"}
  Evidence: "{evidence_snippet}"
- {section}: "{title}" — Acknowledged without applying because {reason or "no suggested_fix — user acknowledged"}
  Evidence: "{evidence_snippet}"

Round 2 — applied (N entries):
...
</prior-decisions>

Phases 3-5: Synthesis, Presentation, and Next Action

Included References

Subagent Template

Findings Schema