Menu
Review requirements, plans, or specs with role-specific lenses. Use when the user wants to improve an existing planning document.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Explore vague or ambitious ideas into a right-sized requirements-only unified plan. Use when the user wants to brainstorm, think through scope, decide what to build, or needs collaborative product framing before planning. Also use when the user must scope work in territory they say they do not know ("I know nothing about X but need to...") or asks for a blindspot pass โ mapping the decision surface before questions begin. Not for executing already-specified work โ direct implementation, debugging, or code review where no product scope is left to decide. Not for a decisive verdict on whether to adopt or switch to a specific external technology, library, or platform โ brainstorming scopes what to build, not whether to commit to an outside option.
Structured code review for bugs, regressions, tests, and standards. Use before PRs or when asked for review; report-only by default, with explicit local apply available for user-directed fix workflows.
Refresh the repo's captured learnings against the current codebase. Use when auditing stale, overlapping, superseded, or drifted learnings; avoid general refactor, debugging, or code review unless the learnings store is explicit.
Document a recently solved problem as a durable repo learning, or capture project vocabulary in CONCEPTS.md. Use when capturing a learning after work.
Diagnosis loop for bugs and failing behavior. Use for errors, stack traces, regressions, failed tests, issue-tracker bugs, stuck investigations after failed fixes, or asks to debug/fix a bug.
Create a durable, visual teaching artifact โ plus an optional check-in (predict-then-reveal for diffs, corrected exercises) that makes it stick โ for something worth learning: a concept, a diff, an idea, or a window of your own recent work. Use when the user wants to be taught, wants a deep explainer, wants to understand a substantial change, or wants a work recap built for retention. Not for ordinary Q&A, brief 'why?' follow-ups, operational diagnosis, status updates, or a concise trade-off answer that belongs inline in chat. For learning, not repo docs or verdicts.
| name | ce-doc-review |
| description | Review requirements, plans, or specs with role-specific lenses. Use when the user wants to improve an existing planning document. |
| argument-hint | [mode:headless] [path/to/document.md] |
Review requirements or plan documents through multi-persona analysis. Dispatches generic subagents seeded with skill-local reviewer prompt assets, auto-applies safe_auto fixes, and routes remaining findings through a four-option interaction (per-finding walk-through, auto-resolve with best judgment, Append-to-Open-Questions, Report-only) for user decision.
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.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.Check the invocation 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. Apply the same judgment about which tier each finding belongs in. Only the delivery of non-safe_auto findings changes:
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 routingThe caller receives findings with their original classifications intact and decides what to do with them.
Headless argument contract: Require mode:headless <document-path>, for example mode:headless <path-to-doc>.md.
If mode:headless is not present, run in default interactive mode with the routing question, walk-through, and bulk-preview behaviors documented in references/walkthrough.md and references/bulk-preview.md.
This skill reviews a document at a path it is handed and, in interactive mode with no path given, discovers the most recent plan under <root>/plans/. Resolve <root> (per the block below) only in that no-path discovery branch โ the sole place it composes a <root>/ path. A review of an explicitly-named document reads that path directly and never resolves <root>; do not run root resolution at the start of every run, since a valid headless or absolute-path review (e.g. /tmp/plan.md, possibly outside any git repo) must not depend on a repo root or CE config it does not need.
Resolve the CE artifact root <root> before composing any artifact path.
docs_root from <repo-root>/.compound-engineering/config.local.yaml, then config.yaml; first non-empty value wins (<repo-root> = git rev-parse --show-toplevel). Unset -> <root> is docs, exactly as before..git/. Otherwise stop with an error naming docs_root and the value -- never fall back to docs.<root> as the sole artifact location: create it if absent, compose each path as <root>/<subdir> with this skill's own subdirectory, and never also read docs.If a document path is provided: Read it, then proceed. If the Read fails or the file is not on disk, apply the missing-document gate below instead of continuing.
If no document is specified (interactive mode): Ask which document to review, or find the most recent under <root>/plans/ using a file-search/glob tool (e.g., Glob in Claude Code).
If no document is specified (headless mode): Output "Review failed: headless mode requires a document path. Expected arguments: mode:headless " and stop without dispatching reviewers.
Missing-document gate โ verify before any dispatch. Persona reviewers read documents from the filesystem, and several run without Bash, so they cannot read git refs โ a path that exists only on a branch that is not checked out wastes the entire persona team discovering they cannot proceed (issue #925). Before Phase 2, confirm every resolved document path is readable on disk (the Read above succeeded). Location does not matter: an absolute path outside the checkout (e.g. /tmp/plan.md) or a doc in another checkout reviews fine. If any path is not readable, do not dispatch any personas:
Classify the document by reading its content shape and metadata, not its file path. Under the unified plan contract a requirements-only and an implementation-ready plan both live in <root>/plans/, so location no longer signals type โ a requirements-style doc classifies as requirements and a plan-shaped doc as plan wherever either sits. The reviewers below operate differently depending on this classification, so misclassifying a plan-shaped doc as a requirements doc (or vice versa) produces noisy or under-scrutinized findings.
First check for the unified artifact contract:
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) 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.active, in_progress, completed, done) are a document-contract finding, not an execution state to honor.Use these signals to decide:
requirements signals (what-to-build documents):
actors:, flows:, acceptance_examples:, or status: carrying brainstorm-shaped valuesAcceptance Examples, Actors, Key Flows, User Flows, Outstanding Questions, Resolve Before PlanningR1, R2, A1, F1, AE1 โ requirement, actor, flow, and acceptance-example IDsplan signals (how-to-build documents):
type: feat|fix|refactor, origin: docs/brainstorms/..., or product_contract_source: ce-brainstorm|ce-plan-bootstrap|legacy-requirementsImplementation Units, Output Structure, Key Technical Decisions, Risks & Dependencies, System-Wide ImpactU1, U2 โ implementation unit IDsGoal, Files, Approach, Test scenarios, VerificationTie-breaker rule. When the content signals are mixed or sparse, treat the dominant content shape as authoritative; if shape is genuinely ambiguous, default to requirements (the more conservative classification โ it activates fewer plan-specific feasibility checks). Path location does not disambiguate type under the unified plan contract, where requirements-only and implementation-ready plans share <root>/plans/; a legacy origin: docs/brainstorms/... field, when present, still reads as a plan signal per the frontmatter list above.
Pass the classification result to each persona via the {document_type} slot in the subagent template. Personas read this and adapt their analysis accordingly.
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. The system's users may be end users, developers, operators, maintainers, or any other audience -- the criteria are domain-agnostic. 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 -- not merely describing a task or restating known requirements:
Leg 2 โ Strategic weight: The proposed work could affect system trajectory, user perception, or competitive positioning, even if the premise is sound:
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 a high-value challenge surface, not merely structural complexity. Routine plans with stated rationale are not by themselves an adversarial signal โ premise/assumption work re-litigates settled questions when the only signal is "this plan is well-structured." Activate when ANY of the following holds:
origin: requirements doc and no product_contract_source: ce-brainstorm or legacy-requirements) -- premise wasn't validated upstreamDo NOT activate adversarial on a routine plan document that derives from a validated upstream Product Contract, stays within scope, and does not introduce high-stakes domains or new abstractions. Validated upstream provenance includes legacy origin: docs/brainstorms/..., product_contract_source: ce-brainstorm, and product_contract_source: legacy-requirements. A direct product_contract_source: ce-plan-bootstrap plan is greenfield and does not suppress premise-level techniques by itself. The plan's structural decisions (more units, more rationale) are not by themselves adversarial signal -- those are the plan doing its job.
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-reviewerDispatch generic subagents using bounded parallelism with the platform's subagent primitive (e.g., Agent in Claude Code, spawn_agent in Codex) where available; otherwise run the work inline or serially. Omit the mode parameter so the user's configured permission settings apply. Respect the current harness's active-subagent limit: queue selected reviewers, dispatch only as many as the harness accepts, and fill freed slots as reviewers complete. Treat active-agent/thread/concurrency-limit spawn errors as backpressure, not reviewer failure: leave the reviewer queued and retry after a slot frees. Record a reviewer as failed only after a successful dispatch times out/fails, or when dispatch fails for a non-capacity reason.
For each selected reviewer, read the matching skill-local prompt asset at references/personas/<reviewer-name>.md and pass its full content as {persona_file}. Do not dispatch standalone agents by type/name and do not rely on platform-level custom-agent registration.
Model tiering lives here, not in prompt assets. Local prompt files have no frontmatter and carry no model metadata. Apply these dispatch-time preferences when the platform exposes a known model override; otherwise omit the override and inherit the parent model rather than guessing a platform-specific model name:
coherence-reviewer: cheapest capable extraction/reasoning tier.design-lens-reviewer, scope-guardian-reviewer: platform mid-tier model.security-lens-reviewer, feasibility-reviewer, product-lens-reviewer, adversarial-document-reviewer: inherit the parent model unless the harness has an established high-capability review tier.Each subagent receives the prompt built from the subagent template included below with these variables filled:
| Variable | Value |
|---|---|
{persona_file} | Full content of the selected local prompt asset from references/personas/ |
{schema} | Content of the findings schema included below |
{document_type} | "requirements", "plan", "unified-requirements", or "unified-plan" from Phase 1 classification |
{document_path} | Path to the document |
{origin_path} | Upstream Product Contract provenance extracted once during Phase 1: prefer the document's origin: frontmatter field when present; otherwise use product_contract_source:<value> when present; otherwise use none. Personas that adapt on origin/provenance (product-lens, adversarial, scope-guardian) read this slot to gate technique suppression โ they do NOT re-parse frontmatter themselves. |
{settled_ktds} | Session-settled decisions extracted once during Phase 1: any Key Technical Decision or Product Contract Key Decision entries carrying a session-settled: annotation, listed as decision name, class (user-directed / user-approved), and rejected alternative; or the literal none when the document has no such entries. Personas read this slot โ they do NOT re-parse the document for it. |
{document_content} | Reviewer-specific section slice. For unified artifacts, pass metadata, Goal Capsule, and only the relevant slice: product-lens/adversarial/scope reviewers get Product Contract; feasibility/coherence reviewers also get Planning Contract and active Implementation Units/Verification/DoD when artifact_readiness: implementation-ready. For legacy documents, pass the full document. |
{decision_primer} | Cumulative prior-round decisions in the current session, or an empty <prior-decisions> block on round 1. See "Decision primer" below. |
For legacy requirements/plan documents, pass each subagent the full
document โ do not split into sections. For unified artifacts, do not pass the
full artifact to every reviewer by default: unified plans can be large, so
section slices (per the {document_content} slot above) are the default.
Escalate to a broader slice only when the reviewer needs cross-section
traceability that the initial slice cannot assess.
On round 1 (no prior decisions), set {decision_primer} to:
<prior-decisions>
Round 1 โ no prior decisions.
</prior-decisions>
On round 2+ (after one or more prior rounds in the current interactive session), accumulate prior-round decisions and render them as:
<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}"
- {section}: "{title}" โ Withdrawn because {triggering decision}
Evidence: "{evidence_snippet}"
Round 2 โ applied (N entries):
...
</prior-decisions>
Each entry carries an Evidence: line because synthesis R29 (rejected-finding suppression) and R30 (fix-landed verification) both use an evidence-substring overlap check as part of their matching predicate โ without the evidence snippet in the primer, the orchestrator cannot compute the >50% overlap test and has to fall back to fingerprint-only matching, which either re-surfaces rejected findings or suppresses too aggressively. The {evidence_snippet} is the first evidence quote from the finding, truncated to the first ~120 characters (preserving whole words at the boundary) and with internal quotes escaped. If a finding has multiple evidence entries, use the first one; the rest live in the run artifact and are not needed for the overlap check.
Accumulate across all rounds in the current session. Skip, Defer, and Acknowledge actions all count as "rejected" for suppression purposes โ each signals the user decided the finding wasn't worth actioning this round (Acknowledge is the no-fix-guard variant: the user saw a finding with no suggested_fix, chose not to defer or skip explicitly, and recorded acknowledgement instead; for round-to-round suppression that is semantically equivalent to Skip). Withdraw is conditional (it is the revalidation variant: an earlier decision resolved or contradicted the finding; see "Withdrawing findings the user's earlier answers resolved" in references/walkthrough.md): it counts as rejected-class only when a user decision retired it โ a settled premise (Skip/Defer) or a user-asserted fact. An Apply-triggered Withdraw never does (its resolution depends on the staged edit both landing and semantically resolving the finding, which round N+1 re-synthesis checks โ not R29; suppressing it would hide a fix that failed or landed ineffectively). Applied findings stay on the applied list so round-N+1 personas can verify fixes landed (see R30 in references/synthesis-and-presentation.md).
Cross-session persistence is out of scope. A later review of the same document starts with a fresh round 1 and no carried primer, even if prior sessions deferred findings into the document's Open Questions section.
Error handling: If a subagent fails or times out, proceed with findings from subagents that completed. Note the failed reviewer in the Coverage section. Do not block the entire review on a single reviewer failure.
Dispatch limit: Even at maximum (7 agents), use bounded parallel dispatch. If the harness cap is lower than the selected team size, queue the remainder and launch them as active reviewers complete.
If any of the conditional judgment trio โ adversarial-document-reviewer, product-lens-reviewer, security-lens-reviewer โ was activated, load references/cross-model-review.md and follow it for the additive, non-blocking peer pass. Attest the host as a harness plus serving family, resolve one target and one concrete route for the whole document, verify every actual recipient against the egress allowlist, and disclose and sanction that fixed route before content leaves the host. cursor means Cursor default/Auto; composer means an explicit Composer-family model through Cursor. Try the declared mapping first; after an observed incompatibility only, a target-bound same-family model override may adapt a stale default. Never silently change an explicit model or recipient, and never let a dispatched worker choose a recipient-changing fallback.
Launch one detached runner job per activated trio lens plus one whole-doc sweep in the same wave as the in-process reviewers, using the exact invocation contract in the reference. Every trio peer receives its twin's same reviewer-specific slice; whole-doc receives the full document. All calls use the same sanctioned target/route. Poll, reap, attribute, and clean up through the runner; a failure or timeout remains non-blocking and is named in Coverage. Fold findings into ordinary synthesis, but agreement promotion requires the artifact's top-level independence_verified: true; false or absent independence is useful evidence, not different-model corroboration. Feasibility and the convergent lenses (coherence, scope-guardian) do not run cross-model.
After all dispatched agents return โ including any cross-model <reviewer-name>-<provider>.json returns โ read references/synthesis-and-presentation.md for the synthesis pipeline (validate, anchor-based gate, dedup, conditional agreement promotion, resolve contradictions, auto-promotion, route by three tiers with FYI subsection), safe_auto fix application, headless-envelope output, and the handoff to the routing question. Peer findings enter ordinary synthesis, but only an artifact with independence_verified: true counts as an independent reviewer for promotion.
For the four-option routing question and per-finding walk-through (interactive mode), read references/walkthrough.md. For the bulk-action preview used by best-judgment routing, Append-to-Open-Questions, and walk-through Auto-resolve with best judgment on the rest, read references/bulk-preview.md. Do not load these files before agent dispatch completes.
@./references/subagent-template.md
@./references/findings-schema.json
Selected reviewer prompt assets live under references/personas/. Read only the prompt files selected for the current review.