| 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:
- Search for
--iterations <N> (case-sensitive, whitespace-separated). The flag may appear
anywhere in the arguments.
- 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
- If the flag is absent, set
TOTAL_ITERATIONS = 2 (default)
- 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:
- If argument starts with
@ or contains / or ends in .md: use as file path, derive directory
- If argument is a 3-digit number (e.g.,
001): search agile/product/ for matching directory
- If no argument: scan
agile/product/ for directories where prd.md has status: APPROVED
or status: REVIEW (both indicate "ready for expert review")
- 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
- Read full
prd.md — this becomes CURRENT_DRAFT
- Extract section headers for the locking mechanism
- Initialize state:
LOCKED_SECTIONS = []ITERATION = 0CHANGE_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 onITERATION_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:
- Collect findings — Parse each agent's structured output
- Group by section — Organize findings by which PRD section they target
- Identify consensus — Where do multiple agents agree? These carry more weight.
- Identify conflicts — Where do agents disagree? Present both sides to the user.
- Lock candidates — Sections where ALL agents reported "no issues" are candidates for locking.
- Build delta — Proposed changes with rationale, grouped by section
- 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:
- Accept — Apply proposed changes to
CURRENT_DRAFT. Record in CHANGE_LOG.
- Accept with modifications — Apply user's modified version. Record in
CHANGE_LOG.
- Reject — No changes. Record rejection reason in
CHANGE_LOG.
- 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
- 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**
- 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.
