review

name	review
description	Plans, before execution — adversarial review of epic docs and stories. Agents from the party roster examine planning artifacts through their professional lens, challenging assumptions, spotting gaps, and flagging risks. Can optionally auto-generate remediation tasks or stories from the findings. Triggers on "/cpm:review".

Adversarial Review

Run a critical review of an epic doc or a specific story using the party agent roster. Each persona examines the artifact through their professional lens — challenging assumptions, spotting gaps, and flagging risks. Produces a structured review document with severity-tagged findings and an optional autofix that generates remediation tasks.

Input

Check for input in this order:

1. If $ARGUMENTS references a file path (e.g. docs/epics/01-epic-auth.md), use that as the epic doc. If it also includes a story number (e.g. docs/epics/01-epic-auth.md 2), note that as the target story for a story-level review.
2. If $ARGUMENTS is a review file path from a previous /cpm:review run (e.g. docs/reviews/01-review-auth.md), read its **Source**: field to resolve the original epic doc. Offer to re-review or continue from the previous findings.
3. If no path given, look for the most recent docs/epics/*-epic-*.md file and ask the user to confirm.
4. If no epic docs exist, tell the user there's nothing to review and stop.

After resolving the epic doc, read it with the Read tool. Then ask the user about review scope:

• Review the entire epic — All stories and tasks will be examined
• Review a specific story — User selects which story to focus on

For story-level review, present the list of stories from the epic doc and let the user choose. If a story number was provided in $ARGUMENTS, skip the selection and use that story directly.

Stale-Progress Check

Follow the shared Stale-Progress Check procedure (from the CPM Shared Skill Conventions loaded at session start).

Roster Loading

Follow the shared Roster Loading procedure. After loading, confirm the roster and how many agents are available: "Review roster loaded: {N} agents available. I'll select the most relevant reviewers based on the content."

Retro Check

Follow the shared Retro Awareness procedure before Agent Selection.

Retro incorporation (this skill):

• All categories: Use the selected cross-retro observations (chosen per the shared Retro Awareness procedure, by relevance across all retros — not just the newest file) as adversarial review prompts for the selected agents — "a retro flagged criteria gaps in auth flows; check whether this artifact has the same risk." This makes review actively guard against recurring failure modes, including ones surfaced by older but on-topic retros.
• Codebase discoveries and patterns worth reusing: Pre-load these as context for reviewer agents that critique structure or implementation.
• Scope surprises and complexity underestimates: Use as prompts for the agents critiquing scope and effort.

Library Check

Follow the shared Library Check procedure with scope keyword review. Deep-read selectively when reviewer personas need context from architecture or coding-standards docs — e.g. an architect reviewing structural decisions, or a developer citing coding standards.

Template Hint (Startup)

After the Library Check and before Agent Selection, display:

Output format is fixed (used by downstream skills). Run /cpm:templates preview review to see the format.

Agent Selection

Select agents dynamically based on the review scope and content. The goal is to match reviewer expertise to what's being reviewed.

Selection Rules

• Story-level review: Pick 2-3 agents whose expertise is most relevant to the story's content.
• Epic-level review: Pick 3-4 agents covering the broadest range of concerns across all stories.

Selection Criteria

For each story or epic, assess the content and match agents by relevance:

• Technical implementation (API endpoints, data models, algorithms) → Developer, Architect
• User-facing features (UI flows, forms, notifications) → UX Designer, Product Manager
• Infrastructure and deployment (CI/CD, environments, scaling) → DevOps Engineer, Architect
• Data handling and security (auth, encryption, PII) → QA Engineer, Architect, Developer
• Process and scope (story sizing, dependency chains, delivery risk) → Scrum Master, Product Manager
• Documentation and naming (terminology, clarity, consistency) → Technical Writer

Always include at least one agent who will challenge the business value of the work (PM or Scrum Master) and at least one who will challenge the technical approach (Developer or Architect). This ensures every review has both a "should we?" and a "can we?" perspective.

Named Agent Format

Each agent's review contribution uses the format:

{icon} **{displayName}**: {review content}

This matches the party mode format for consistency across CPM skills.

Subagent Delegation

When to use subagents (the Agent tool) vs. working inline. Subagents are valuable for parallelising large, genuinely independent work and protecting the main context window from excessive results — but they add overhead and lose conversational context.

Opus 5 delegates readily, so the guidance below is about restraint rather than encouragement. Delegation earns its overhead only when the work is large, genuinely independent, and parallelisable; anything smaller is faster and clearer done inline.

Delegate (fan-out) when

Each case below assumes the work is large enough to repay the overhead. Where it is not, work inline.

• Reading many independent files: e.g. reading 5+ library documents, scanning multiple epic docs, or auditing files across directories. Each read is independent, and fanning out keeps the results out of the main context.
• Per-item work across a long list: e.g. reviewing each story in isolation, or examining one artifact through several reviewer lenses at once. The items share no state, so they parallelise cleanly.
• Broad exploratory research: e.g. sweeping the codebase for a pattern across many directories, or surveying an unfamiliar project structure. The search results inform a decision but are not themselves the deliverable.

Two cases fall outside this even when they look like the ones above:

• Work completable in a handful of tool calls stays inline. A search you could run yourself in two or three calls costs more to delegate than to do — the spawn overhead and the round trip outweigh the saving.
• Verification of your own work stays inline. Do not use subagents to verify, double-check, or second-guess something you just did. A subagent starting from no context is a poor auditor of work it did not see, and the pattern compounds with the self-checking the model already performs.

Work inline when

• The result drives the next step: e.g. reading a file to decide what to edit next, or checking a test result before proceeding. Sequential dependencies require inline execution.
• The code is already in context: e.g. you just read the file, or the user pasted it. Delegating would re-read what you already have.
• User interaction is needed: e.g. AskUserQuestion gates, facilitation loops, or confirmation steps. Subagents cannot interact with the user.
• The work is a single focused operation: e.g. one edit, one test run, one file creation. The overhead of spawning outweighs the benefit.

Rules

• Subagents start with no context from the current conversation — the prompt must be self-contained.
• If one subagent can complete the task, use one rather than several, and keep spawn counts low.
• Assign subagents to research and exploration, not to implementation decisions that require conversational context.
• When delegating, specify whether the subagent should write code or just research. The subagent cannot infer intent from the conversation.

Process

State tracking: Create the progress file before Step 1 and update it after each step completes. See State Management below for the format and rationale. Delete the progress file once the final review file has been saved.

Step 1: Analyse the Artifact

Read the target artifact (full epic or specific story) and build a structured understanding:

• For epic-level review: Parse all ## story headings, their acceptance criteria, tasks, dependencies, and status. Note the epic's overall structure — how many stories, dependency chains, completion state.
• For story-level review: Parse the target ## story heading, its acceptance criteria, all ### tasks, and any **Blocked by** dependencies. Also note the story's position within the broader epic for context.

Spec discovery: If the epic doc has a **Source spec**: field, read the referenced spec. This enables spec compliance review — checking whether the epic's stories cover the spec's requirements. If no spec exists, skip silently.

ADR discovery: Glob docs/architecture/[0-9]*-adr-*.md. If ADRs exist, read them. This enables ADR compliance review — checking whether stories respect architectural decisions. If no ADRs exist, skip silently.

Present a brief summary to the user: what's being reviewed, how many stories/tasks, current status. If a spec or ADRs were found, note that they'll be used as review context.

Step 2: Conduct Adversarial Review

This is the core of the skill. Each selected agent examines the artifact through their professional lens and produces findings.

Review Dimensions

Agents should look for issues across these concern types:

• Unclear Requirements — Acceptance criteria that are vague, ambiguous, or untestable. Stories where the definition of done is subjective.
• Missing Acceptance Criteria — Important outcomes that aren't captured. Edge cases, error states, or integration points that should have criteria but don't.
• Hidden Complexity — Tasks that look simple but have non-obvious implementation challenges. Underestimated work that will cause delays.
• Architectural Risks — Structural decisions that could cause problems at scale, create tight coupling, or conflict with existing patterns in the codebase.
• Testability Concerns — Stories or tasks that would be difficult to verify. Acceptance criteria that can't be automatically checked.
• Scope Creep — Stories that try to do too much, tasks that go beyond their parent story's acceptance criteria, or work that belongs in a different epic.
• Dependency Risks — Missing or incorrect **Blocked by** declarations. Circular dependencies. Stories that should be sequenced but aren't.
• Spec Compliance — Stories or acceptance criteria that don't align with the spec's requirements. Must-have requirements that aren't covered by any story. Only applicable when a source spec was discovered in Step 1.
• ADR Compliance — Stories or tasks that contradict or ignore architectural decisions from existing ADRs. Implementation approaches that conflict with the rationale or constraints documented in ADRs. Only applicable when ADRs were discovered in Step 1.
• Missing Test Coverage — Stories with acceptance criteria tagged [unit], [integration], or [feature] that lack a corresponding testing task. Stories where criteria warrant automated testing but have no test approach tags. Only applicable when the source spec has a testing strategy or when stories carry test approach tags.

Not every agent reviews every dimension. Each agent focuses on what they'd naturally notice given their role:

• Product Manager: Unclear requirements, scope creep, missing user value, spec compliance
• Architect: Architectural risks, hidden complexity, dependency risks, ADR compliance
• Developer: Hidden complexity, testability concerns, missing acceptance criteria, ADR compliance, missing test coverage
• UX Designer: Unclear requirements from a user perspective, missing edge cases in user flows
• QA Engineer: Testability concerns, missing acceptance criteria, missing error states, missing test coverage
• DevOps Engineer: Architectural risks (deployment, scaling), dependency risks
• Technical Writer: Unclear requirements (naming, terminology), scope creep (documentation gaps)
• Scrum Master: Scope creep, dependency risks, story sizing concerns

Severity Classification

Each finding must be tagged with exactly one severity level:

• Critical — Blocks execution. The story or task cannot be implemented correctly as written. Examples: contradictory acceptance criteria, impossible dependency chain, missing essential requirement.
• Warning — Likely to cause problems. Implementation can proceed but will probably hit issues. Examples: vague acceptance criteria that different developers would interpret differently, hidden complexity that makes time estimates unreliable.
• Suggestion — Improvement opportunity. Not blocking and may not cause problems, but addressing it would improve quality. Examples: acceptance criteria that could be more specific, a task that could be split for clarity.

Review Execution

Subagent fan-out (when 3+ agents are selected): Each agent's review is independent — they examine the same artifact from different perspectives with no shared state, which is the case the Subagent Delegation section above treats as genuinely parallelisable. Spawn at most one subagent per selected reviewer agent: the selected agent count is the cap, and the spawn count never exceeds it. Fan-out here is a permitted path, not the expected one — with two agents, or where the artifact is small enough to review in a handful of passes, inline is the cheaper and clearer route. Each subagent's prompt should include: the artifact content, the agent's persona (icon, displayName, role, personality), the review dimensions relevant to their role, the severity classification scheme, the finding format, and the coverage-first instruction from step 2 below. A subagent not told to report everything will curate on its own, which is the suppression Step 2b exists to prevent. Consolidate findings from all subagents after they complete.

Inline execution (when 2 agents are selected or fan-out is unavailable): Review with each agent in turn within the main context.

For each agent (whether via subagent or inline):

1. Review the artifact through the agent's professional lens.
2. Report every finding the lens surfaces. This is the finding stage, and its job is maximum coverage rather than curation — do not suppress an observation for seeming minor, and do not pre-rank. Filtering and ranking happen later, at Step 2b.
3. Tag each finding with a concern type and severity.
4. Reference specific stories, tasks, or acceptance criteria by number.
5. If library documents were loaded, reference relevant standards or constraints where they apply.

Format each finding as:

{icon} **{displayName}** [{severity}]: {finding}
→ {story/task reference}: {specific issue and why it matters}

Step 2b: Filter and Rank

Consolidate every agent's findings, then curate. The finding stage above stays comprehensive; selection happens here — the same find/rank separation audit keeps between its complete findings table and its Executive Summary.

Weigh severity against how well each finding is evidenced, then select down to the review's depth: 3-8 findings for a single-story review, 5-15 for a full epic review. Findings that do not make the cut stay in this session and are not carried into the review document, whose schema records the curated set (Step 3). The cap belongs here and not in the finding stage: a cap the finders can see is a cap they stop short of, and what goes unfound cannot be curated back.

Step 2c: Present

After filtering, present the curated findings to the user grouped by concern type (not by agent). Within each concern type, order by severity (critical first, then warning, then suggestion).

Progress note: capture concern types and the finding count by severity as reported in the Step 2 summary, and the curated count in the Step 2b summary.

Step 3: Write Review File

Save the review to docs/reviews/{nn}-review-{slug}.md. Create the docs/reviews/ directory if it doesn't exist.

• {nn} is assigned by the shared Numbering procedure (from the CPM Shared Skill Conventions loaded at session start).
• {slug} is derived from the epic doc name (e.g. epic doc 01-epic-auth.md produces review slug auth). For story-level reviews, append the story number: auth-s2.

Format:

# Review: {Epic or Story Title}

**Date**: {today's date}
**Source**: {path to epic doc}
**Scope**: {Epic | Story N: {Story Title}}
**Agents**: {comma-separated list of agent displayNames who participated}
**Findings**: {total count} ({critical count} critical, {warning count} warnings, {suggestion count} suggestions)

## Summary

{2-3 sentence overview of the review — overall assessment, most significant concerns, and whether the artifact is ready for execution or needs attention.}

## Findings

### Unclear Requirements
{findings in this category, ordered by severity}

- **[{severity}]** {icon} **{agent}**: {finding}
  → {story/task reference}: {specific issue}

### Missing Acceptance Criteria
{findings in this category}

### Hidden Complexity
{findings in this category}

### Architectural Risks
{findings in this category}

### Testability Concerns
{findings in this category}

### Scope Creep
{findings in this category}

### Dependency Risks
{findings in this category}

### Spec Compliance
{findings in this category — only if a source spec was discovered}

### ADR Compliance
{findings in this category — only if ADRs were discovered}

### Missing Test Coverage
{findings in this category — only if test approach tags or testing strategy present}

Only include concern type sections that have findings. If a category has no findings, omit the heading entirely.

Step 4 may append a ## Remediation section to this file — see Autofix below.

Tell the user the review file path after saving.

An artifact can be published from this output on request — follow the shared Artifact Publishing procedure. It is always separately confirmed, and never the default.

For review the artifact is a findings explorer by severity: findings ordered worst-first and filterable across the concern-type categories, so a long review is triaged in one pass. The Markdown groups by category because a document has to pick one ordering; the explorer lets the reader pick the other. As with companion assets, if you cannot write the one-line justification for what the visual carries that the prose cannot, it has not earned its place.

Step 4: Autofix

After writing the review file, offer the user the option to generate remediation tasks from the findings. This step is optional — the user can skip it entirely.

Decision Gate

If the review produced no critical or warning findings, skip autofix entirely — there's nothing actionable to fix. Inform the user: "No critical or warning findings — skipping autofix." Use the Edit tool to append a ## Remediation section to the review file:

## Remediation

No critical or warning findings — autofix not applicable.

If critical or warning findings exist, present the autofix option using AskUserQuestion:

• Generate fix tasks — Create remediation items from critical and warning findings
• Skip autofix — Proceed to pipeline handoff without generating tasks

If the user chooses Skip autofix, use the Edit tool to append a ## Remediation section to the review file before proceeding to Step 5:

## Remediation

Autofix offered but declined. {N} critical and {N} warning findings remain unaddressed.

Suggestions are informational and always remain as-is — only critical and warning findings generate fix tasks.

Adaptive Path Selection

When the user opts into autofix, determine the target based on the epic's status:

1. Read the epic doc's top-level **Status**: field.
2. If Pending or In Progress (active epic): Use the epic amendment path — append a remediation story to the epic doc.
3. If Complete or if the epic doc doesn't exist: Use the standalone task path — create Claude Code tasks directly.

Epic Amendment Path (Active Epics)

When the epic has pending work, append a remediation story to the epic doc. This keeps fix tasks within the planning artifact so cpm:do picks them up naturally.

1. Determine the next story number: Read the epic doc, find the highest **Story**: {N} number, and increment by 1.

2. Build the remediation story: Create a new ## story section from the critical and warning findings. Each finding becomes a task within the story.

   Format:

   ## Address review findings
   **Story**: {next N}
   **Status**: Pending
   **Blocked by**: —
   
   **Acceptance Criteria**:
   - Each critical and warning finding from the review has been addressed
   - Existing acceptance criteria on other stories continue to pass
   
   ### Fix: {finding summary}
   **Task**: {N.1}
   **Description**: [{severity}] {full finding text with story/task reference}
   **Status**: Pending
   
   ### Fix: {finding summary}
   **Task**: {N.2}
   **Description**: [{severity}] {full finding text with story/task reference}
   **Status**: Pending
   
   ---
   

3. Append using Edit tool: Use the Edit tool to append the new story section to the end of the epic doc (before any ## Lessons section if one exists). Always use Edit — it preserves the existing content.

4. Report: Tell the user what was added — story number, task count, and which findings were converted.

5. Update review file: Use the Edit tool to append a ## Remediation section to the review file:

   
   ## Remediation
   
   **Path**: Epic amendment
   **Target**: {epic doc path}
   **Story**: {story number} — Address review findings
   
   | # | Finding | Severity | Task |
   |---|---------|----------|------|
   | 1 | {finding summary} | {severity} | {N.1} |
   | 2 | {finding summary} | {severity} | {N.2} |
   

   Include one row per finding that generated a task. The Task column references the task number within the remediation story.

Standalone Task Path (Complete or Missing Epics)

When the epic is complete or no epic doc exists, create Claude Code tasks directly. This avoids reopening a completed planning artifact.

1. Build tasks from findings: For each critical and warning finding, create a Claude Code task:

   TaskCreate:
     subject: "Fix: {finding summary}"
     description: "[{severity}] {full finding text}\n\nSource review: {review file path}\nOriginal artifact: {epic doc path}\n{story/task reference}"
     activeForm: "Fixing: {finding summary}"
   

2. Set dependencies: If findings have a logical order (e.g. a critical finding should be addressed before a related warning), use TaskUpdate with addBlockedBy to sequence them. Otherwise, leave all tasks independent.

3. Report: Tell the user how many tasks were created and list them briefly.

4. Update review file: Use the Edit tool to append a ## Remediation section to the review file:

   
   ## Remediation
   
   **Path**: Standalone tasks (epic complete)
   **Tasks created**: {count}
   
   | # | Finding | Severity | Task |
   |---|---------|----------|------|
   | 1 | {finding summary} | {severity} | {task subject} |
   | 2 | {finding summary} | {severity} | {task subject} |
   

   Include one row per finding that generated a task. The Task column uses the Claude Code task subject.

Step 5: Pipeline Handoff

After autofix (or after skipping it), offer the user options for what to do next. The options adapt based on the epic's status.

Pre-Execution Epics (Status: Pending or In Progress)

Use AskUserQuestion with these options:

• Continue to /cpm:pivot — Use the review findings to amend the epic doc or its upstream spec. Pass both the review file path and the epic doc path as context.
• Continue to /cpm:do — Proceed to task execution. Pass the epic doc path as context. The review findings serve as informational background.
• Just exit — End the session, no handoff.

Post-Execution Epics (Status: Complete)

Use AskUserQuestion with these options:

• Continue to /cpm:retro — Feed review findings into a retrospective. Pass the review file path and epic doc path as context.
• Continue to /cpm:pivot — Use the review findings to amend the epic doc or upstream artifacts. Pass both paths as context.
• Continue to /cpm:discover — Start a new planning cycle informed by the review. Pass the review file path as context.
• Continue to /cpm:spec — Build requirements informed by the review. Pass the review file path as context.
• Just exit — End the session, no handoff.

Handoff Execution

If the user chooses a pipeline skill, pass the relevant file paths as the input context for that skill. The review file path becomes the $ARGUMENTS equivalent — the next skill should treat it as its starting context.

Delete the progress file after handoff or exit.

State Management

Follow the shared Progress File Management procedure, writing to docs/plans/.cpm-progress-{session_id}.md — or docs/plans/.cpm-progress.md when CPM_SESSION_ID is not in context. /cpm:clean, the Stale-Progress Check and compaction recovery all locate the file by globbing that exact stem, so one named anything else is invisible to every reader it exists for.

Lifecycle:

• Create: before starting Step 1 (ensure docs/plans/ exists).
• Update: after each step completes.
• Delete: only after the final review file has been saved and any autofix/handoff is complete.

Format:

# CPM Session State

**Skill**: cpm:review
**Step**: {N} of 5 — {Step Name}
**Output target**: docs/reviews/{nn}-review-{slug}.md
**Input source**: {path to epic doc}
**Review scope**: {Epic | Story N}
**Agents selected**: {comma-separated agent displayNames}

## Completed Steps

### Step 1: Analyse the Artifact
{Summary — what was reviewed, story/task counts, status}

### Step 2: Conduct Adversarial Review
{Summary — finding counts by severity and concern type, key themes}

### Step 2b: Filter and Rank
{Summary — findings consolidated vs findings carried forward, and what the cut turned on}

### Step 3: Write Review File
{Summary — file path written, finding totals}

### Step 4: Autofix
{Summary — path chosen (epic amendment or standalone tasks), items generated, or skipped}

### Step 5: Pipeline Handoff
{Summary — user's choice, context passed}

{...include only completed steps...}

## Next Action
{What to do next}

The "Completed Steps" section grows as steps complete. Each summary should capture the key findings and decisions in enough detail for seamless continuation.

Graceful Degradation

Every scenario below specifies an explicit action sequence ending with a visible result. No silent fallbacks.

• No roster found → Action: Fall back to single-perspective review without agent personas. Result: Report to the user: "Agent roster not found — running single-perspective review without agent personas."

• No library docs → Action: Proceed with review using only the epic doc and spec as context. Result: Report to the user: "No library documents found — reviewing with epic doc and spec context only."

• Malformed epic doc → Action: Parse what is available. Review the portions that can be parsed. Result: Report to the user: "Epic doc has structural issues: {list of problems}. Reviewing {N} of {M} parseable stories."

• Empty review → Action: Write a review file noting the artifact passed review with no concerns. Skip the autofix phase. Result: Report to the user: "Review complete — no findings. Artifact passes review."

Guidelines

• Adversarial, not hostile. The review should challenge assumptions and find real issues, not manufacture criticism. If something is well-designed, say so. Not every story yields many findings.
• Specific over vague. "Story 2's acceptance criteria are unclear" is useless. "Story 2, criterion 3 says 'handles errors gracefully' — what does gracefully mean? Which errors? This will be interpreted differently by different implementers" is actionable.
• Severity matters. Tag each finding at its true severity level. A genuinely critical finding (blocks execution) is rare. Most findings will be warnings or suggestions. That's fine.
• Reference the artifact. Every finding should point to a specific story, task, or acceptance criterion. Reviewers who can't point to what they're criticising aren't being helpful.
• Match depth to scope. A single-story review should take 2-3 agents and produce 3-8 findings. A full epic review should take 3-4 agents and produce 5-15 findings. Scale review depth to artifact size — these are the targets Step 2b curates to, not a cap on what the agents report.