agile-product-refine

name	agile:product:refine
description	Use when an approved Product Requirements Document (PRD) needs expert stress-testing before initiative brainstorming. Five expert agents (Proposer, Challenger, Grounder, Reviewer, Critic) run a configurable number of progressive iterations (default 2, up to 5 via `--iterations N`) to sharpen product vision, validate users and competitive positioning, stress feature decomposition, ground in codebase reality, and verify metrics-and-risk coherence. Produces a refined prd.md (status REFINED) and refinement-report.md. Triggers on: "refine product", "refine PRD", "review product requirements", "stress-test PRD", "challenge PRD", "expert panel for PRD", "improve PRD", "polish PRD before initiatives", "refine product before epics".
user-invocable	true
allowed-tools	["Read","Edit","Write","Glob","Grep","Bash","Agent","AskUserQuestion"]

Product Refine

Stress-test an approved Product Requirements Document (PRD) through a 5-expert refinement panel running a configurable number of iterations (default 2, up to 5 via --iterations N) before the PRD enters initiative brainstorming. Each iteration narrows focus — from product vision down to metrics-and-risks coherence — producing a battle-tested prd.md and an audit trail.

A PRD cascades widest in the agile chain (1 PRD → many initiatives → many epics → many features). Late-stage corrections at epic or feature level cost 10-100x more than PRD-level corrections, so this skill is the highest-leverage review point in the entire agile workflow.

Invocation

• /agile:product:refine @agile/product/001-name/prd.md — Target specific PRD by file path
• /agile:product:refine 001 — Target by product number
• /agile:product:refine — Auto-detect (looks for APPROVED or REVIEW PRDs in agile/product/)
• /agile:product:refine --iterations 3 001 — Override iteration count (default 2, range 1-5)
• /agile:product:refine --iterations 1 @agile/product/001-name/prd.md — Quick single-pass review
• /agile:product:refine --iterations 5 001 — Full-depth refinement, one domain per iteration

The --iterations N flag can appear anywhere in the arguments; the rest of the input is parsed as the PRD path/number after the flag is stripped.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Context

• Current branch: !git branch --show-current
• Recent products: !ls agile/product/ 2>/dev/null | sort | tail -5

Hard Gate

Do NOT modify any PRD until ALL iterations complete (or the user stops early) AND the user gives final approval. Do NOT invoke `agile:initiative:brainstorm`, `agile:epic:brainstorm`, or any implementation skill. This skill refines — it does not advance the pipeline. The user manually proceeds when ready.

Workflow Overview

prd.md [APPROVED]
    ↓
Phase 0: Entry & Validation
    ↓
Phase 1: Iteration Loop (TOTAL_ITERATIONS rounds)
    │
    │  Each iteration:
    │  ┌─ Prepare context ──► Dispatch expert agents ──► Synthesize findings ──► User review ─┐
    │  └────────────────────────────────────────── lock agreed sections ◄────────────────────────┘
    ↓
Phase 2: Commit
    ↓
prd.md [REFINED] + refinement-report.md

---

Phase 0: Entry & Validation

0.1 Parse Iteration Count

Before resolving the PRD path, extract the iteration-count flag from $ARGUMENTS:

1. Search for --iterations <N> (case-sensitive, whitespace-separated). The flag may appear anywhere in the arguments.
2. If found:

• Parse N as a positive integer
• Validate 1 <= N <= 5. If out of range, error and stop: "Iterations must be between 1 and 5 (got N). The canonical focus schedule has 5 stages — running more than 5 would be redundant, fewer than 1 is meaningless."
• Set TOTAL_ITERATIONS = N
• Remove both --iterations and <N> tokens from the argument string before path resolution

3. If the flag is absent, set TOTAL_ITERATIONS = 2 (default)
4. State the resolved count to the user before proceeding: "Running TOTAL_ITERATIONS iteration(s) of refinement against [PRD_DIR]."

This flag value is referenced as TOTAL_ITERATIONS throughout Phase 1-3.

0.2 Resolve PRD Path

Resolve the remaining (flag-stripped) $ARGUMENTS to PRD_DIR using this priority chain:

1. If argument starts with @ or contains / or ends in .md: use as file path, derive directory
2. If argument is a 3-digit number (e.g., 001): search agile/product/ for matching directory
3. If no argument: scan agile/product/ for directories where prd.md has status: APPROVED or status: REVIEW (both indicate "ready for expert review")
4. If exactly one candidate → use it. Multiple → AskUserQuestion to choose. None → error and stop.

0.3 Validate Prerequisites

Check	Requirement	Error if Missing
prd.md exists	File at PRD_DIR/prd.md	"No prd.md found. Run /agile:product:brainstorm first"
Status is reviewable	status: APPROVED or status: REVIEW in YAML	"PRD status is [X]. Refinement requires APPROVED or REVIEW (DRAFT means still drafting; REFINED already done)"

Status lifecycle reference:

DRAFT → REVIEW ────► REFINED → IMPLEMENTED
        APPROVED ──┘  ↑
        ↑              └─ this skill produces this state
        └─ this skill consumes either of these states

Note: agile:product:brainstorm does not enforce a specific output status — the user picks at the preview gate. Both REVIEW (peer review pending) and APPROVED (stakeholder-approved) are valid inputs to refinement; DRAFT means the brainstorm session is still in progress.

0.4 Load Context

1. Read full prd.md — this becomes CURRENT_DRAFT
2. Extract section headers for the locking mechanism
3. Initialize state:

• LOCKED_SECTIONS = []
• ITERATION = 0
• CHANGE_LOG = []

0.5 Identify PRD Sections

The PRD template has these canonical sections (used for locking):

Section ID	Maps to PRD Template Section
executive-summary	§1 Executive Summary (vision, problem, value-prop, category)
target-users	§2 Target Users (primary, scenarios, secondary)
current-vs-future	§3 Current State vs. Future State
competitive-landscape	§4 Competitive Landscape
feature-requirements	§5 Feature Requirements (MoSCoW)
non-functional-requirements	§5 Non-Functional Requirements
risk-assessment	§6 Risk Assessment & Mitigation
success-metrics	§7 Success Metrics
key-assumptions	§7 Key Assumptions Validation (template has duplicate §7)
release-roadmap	§9 Release Roadmap
epic-candidates	§10 Epic Candidates
domain-model	§14 Domain Model
system-interactions	§15 System Interaction Map
traceability	§13 Traceability Chain

---

Phase 1: Iteration Loop

Run TOTAL_ITERATIONS iterations (default 2, configurable via --iterations N, range 1-5). Each has a defined focus domain that narrows progressively. When fewer than 5 iterations are requested, the canonical domains are packed into the available iterations.

Canonical Focus Domains

Five progressive focus domains exist; each iteration covers one or more of them:

Domain	Focus	Lead Agent(s)
D1	Product vision, strategic positioning, problem framing, value proposition	All equal
D2	Target users, user scenarios, competitive landscape, differentiation	All equal
D3	Feature decomposition (MoSCoW), MVP coherence, acceptance criteria, scope boundaries	All equal
D4	Technical feasibility, NFRs, domain model, system interactions, codebase reality	Grounder leads
D5	Success metrics, risks, assumptions, roadmap, epic candidates, final coherence	Reviewer + Critic lead

Iteration Schedule by TOTAL_ITERATIONS

Use this mapping to determine which domains each iteration covers:

TOTAL_ITERATIONS	Iter 1	Iter 2	Iter 3	Iter 4	Iter 5
1	D1+D2+D3+D4+D5	—	—	—	—
2 (default)	D1+D2+D3	D4+D5	—	—	—
3	D1+D2	D3	D4+D5	—	—
4	D1	D2+D3	D4	D5	—
5	D1	D2	D3	D4	D5

Why the default-2 split is D1+D2+D3 / D4+D5 (not D1+D2 / D3+D4+D5 like initiatives): PRDs front-load business/strategic content (vision, users, features) and back-load technical/operational content (NFRs, metrics, risks). Clustering the "what the product is" domains into Iter 1 and the "can we deliver it" domains into Iter 2 mirrors the natural reading order of a PRD and maximizes per-iteration focus.

Dispatch Pattern Rules

The dispatch pattern for each iteration is derived from the domains it covers:

• If the iteration covers only D1, D2, and/or D3 (no codebase grounding needed): launch all 5 agents in parallel.
• If the iteration covers D4 (with or without others): launch Grounder first (needs codebase exploration). When Grounder returns, include its findings in the prompt for the remaining 4 agents, then launch those 4 in parallel.
• If the iteration covers D5 but NOT D4: launch Critic + Reviewer first (D5 lead agents). When they return, include their findings for the remaining 3 agents, then launch those 3 in parallel.
• If an iteration covers D4 and D5 together (as in N=2's second iteration): use the D4 rule — Grounder first, then the other 4 in parallel, with all agents explicitly addressing D5 concerns in their response.
• If an iteration covers all 5 domains (as in N=1): Grounder first, then the other 4 in parallel, and every agent provides a holistic verdict covering all domains.

Per-Iteration Steps

Step 1: Prepare Agent Context

Build the prompt package for each agent. Every agent receives:

• The full CURRENT_DRAFT text
• LOCKED_SECTIONS — list of section IDs agents must NOT comment on
• ITERATION_FOCUS — the focus domain(s) for this iteration (from schedule above)
• CHANGE_LOG — summary of changes from prior iterations (so agents don't re-litigate)

For Grounder (all iterations, but especially any iteration whose focus includes D4):

• Also provide codebase context gathered via Glob/Grep — module listings, file counts, dependency structures relevant to the product scope (services in services/**, entities in common/, gateway patterns in gateways/*, legacy modules in legacy/)

For Reviewer (all iterations):

• Also provide a reference pointer to the PRD validation rubric at .claude/skills/agile-product-brainstorm/templates/prd-validation-checklist.md so the Reviewer can score the PRD against the proven 100-point quality rubric.

Step 2: Dispatch Expert Agents

Launch agents using the Agent tool. Read the agent prompt from the corresponding file in templates/agent-prompts/ and include it in the agent's prompt along with the context package.

Agent prompt files:

Agent	Prompt File	Subagent Type
Proposer	templates/agent-prompts/proposer.md	general-purpose
Challenger	templates/agent-prompts/challenger.md	general-purpose
Grounder	templates/agent-prompts/grounder.md	Explore
Reviewer	templates/agent-prompts/reviewer.md	general-purpose
Critic	templates/agent-prompts/critic.md	general-purpose

Dispatch pattern: Apply the rules defined in the "Dispatch Pattern Rules" subsection above (under "Phase 1: Iteration Loop"), keyed off which focus domains the current iteration covers per the schedule table.

Each agent must return a structured report. See agent prompt files for the expected output format.

Step 3: Synthesize Findings

After all agents return for an iteration:

1. Collect findings — Parse each agent's structured output
2. Group by section — Organize findings by which PRD section they target
3. Identify consensus — Where do multiple agents agree? These carry more weight.
4. Identify conflicts — Where do agents disagree? Present both sides to the user.
5. Lock candidates — Sections where ALL agents reported "no issues" are candidates for locking.
6. Build delta — Proposed changes with rationale, grouped by section
7. Capture Reviewer's score — If Reviewer provided a 100-point rubric score, surface it in the iteration summary.

Step 4: User Touchpoint

Present the iteration summary to the user via AskUserQuestion.

Summary format:

## Iteration N/TOTAL_ITERATIONS: [Focus Domain(s)]

### Reviewer Quality Score: XX/100 ([Rating])

### Consensus Findings (agents agree)
- [Section]: [finding] — recommended change: [change]

### Contested Findings (agents disagree)
- [Section]: Proposer says [X], Challenger says [Y]

### Sections Ready to Lock (all agents: no issues)
- [Section names]

### Proposed Changes
1. [Change description] — supported by: [agent names]
2. [Change description] — supported by: [agent names]

Options for non-final iterations (i.e., when N < TOTAL_ITERATIONS):

["Accept all changes and continue",
 "Accept with modifications — let me explain",
 "Reject all changes — keep current draft",
 "Stop refinement early — I'm satisfied with the current state"]

Options for the final iteration (i.e., when N == TOTAL_ITERATIONS):

["Approve refined PRD — commit",
 "Request one more iteration on specific sections",
 "Reject refinement — keep original PRD"]

Note: if the user selects "Request one more iteration" at the final step, run an additional iteration with the focus domain they specified, then present the final-approval options again. This increments the effective iteration count for the refinement-report.

Step 5: Update State

Based on the user's response:

1. Accept — Apply proposed changes to CURRENT_DRAFT. Record in CHANGE_LOG.
2. Accept with modifications — Apply user's modified version. Record in CHANGE_LOG.
3. Reject — No changes. Record rejection reason in CHANGE_LOG.
4. Stop early — Jump to Phase 2 with current state.

Lock sections — Any section the user accepted that had unanimous "no issues" gets added to LOCKED_SECTIONS. Locked sections are excluded from future iteration prompts.

Anti-reversal rule — If an agent proposes reverting a change from a previous iteration, flag it explicitly: "Agent [X] recommends reverting the [change] from iteration [N]. Original rationale was: [reason]. Do you want to revert?" This prevents oscillation. The brainstorm captured user intent through 13 phases — the anti-reversal flag ensures agents can't silently revert decisions the user already made.

Early termination — If after any iteration ALL remaining unlocked sections receive "no issues" from all agents, present: "All experts agree the PRD is sound. Refinement complete after N iterations." Jump to Phase 2.

---

Phase 2: Commit

2.1 Final Approval

If not already approved in the final iteration's user touchpoint, present the complete refined PRD for final approval via AskUserQuestion:

["Approve and commit",
 "Let me review the full document first",
 "Abort — discard all refinement changes"]

If "review first" — display the full CURRENT_DRAFT. Then re-ask approval.

2.2 Write Artifacts

1. Update prd.md — Overwrite PRD_DIR/prd.md with CURRENT_DRAFT, applying these status changes consistently in both locations the PRD template uses status (otherwise YAML and body will diverge — see prd-template.md lines 4 and 15):

• YAML frontmatter: status: APPROVED (or REVIEW) → status: REFINED
• Body header: **Status**: APPROVED (or REVIEW) → **Status**: REFINED
• YAML frontmatter: update updated: "YYYY-MM-DD" to today's date
• YAML frontmatter: add new line refined: "YYYY-MM-DD" # N iterations after updated:
• Body header: update **Last Updated**: YYYY-MM-DD to today's date
• Body header: add new line **Refined**: YYYY-MM-DD (N iterations) after **Last Updated**

2. Write refinement-report.md — Create PRD_DIR/refinement-report.md using the template at templates/refinement-report-template.md, populated from CHANGE_LOG and iteration data. Include the Reviewer's final 100-point score in the executive summary.

2.3 Git Commit

git add PRD_DIR/prd.md PRD_DIR/refinement-report.md
git commit -m "docs(agile): refined PRD NNN-name (N iterations)"

---

Phase 3: Next Steps

After committing, present:

PRD Refined: PRD_DIR/prd.md

  Iterations completed: N/TOTAL_ITERATIONS
  Sections refined: M
  Sections unchanged: K
  Final quality score: XX/100

  Refinement report: PRD_DIR/refinement-report.md

Next steps — derive initiatives from this PRD:
  /agile:initiative:brainstorm @PRD_DIR/prd.md

Epic candidates already named in this PRD:
  [Epic ID]: [name] (from §10 Epic Candidates)
  [Epic ID]: [name]
  ...

Do NOT invoke any downstream skill. The user decides when to proceed to initiative brainstorming or directly to epic brainstorming.

---

Key Principles

• One question at a time via AskUserQuestion — Every user question goes through this tool.
• Section locking prevents oscillation — Once all experts agree on a section, it's frozen.
• Anti-reversal protection — Reversals require explicit user approval with rationale shown.
• Grounder is the reality anchor — Only agent with codebase access. Keeps the panel grounded.
• Reviewer is the rubric anchor — Scores against the proven 100-point PRD quality rubric.
• Delta-only changes — Agents propose changes, they don't rewrite the document. This prevents introducing new issues during fixes.
• Progressive narrowing — Each iteration has a defined scope. Vision/users/features first; technical feasibility and metrics-and-risks last.
• User controls everything — Every change requires approval. User can stop at any iteration.

Expert Agents

Agent	Prompt File	Focus
Proposer	templates/agent-prompts/proposer.md	Creative alternatives, enhancements, sharper framings
Challenger	templates/agent-prompts/challenger.md	Hidden assumptions, failure modes, devil's advocate
Grounder	templates/agent-prompts/grounder.md	Codebase reality, technical feasibility, NFR feasibility
Reviewer	templates/agent-prompts/reviewer.md	100-pt rubric scoring, completeness, traceability, polish
Critic	templates/agent-prompts/critic.md	Roadmap realism, risk ratings, epic candidate sequencing

Templates

Template	Purpose
templates/refinement-report-template.md	Structure for the refinement audit trail
templates/agent-prompts/*.md	Expert role prompts (5 files)

Terminal State

The terminal state is a committed refined prd.md (status REFINED) and refinement-report.md. Do NOT invoke initiative brainstorm, epic brainstorm, implementation, or any downstream skill. The user manually proceeds when ready.