| name | agile:initiative:refine |
| description | Use when an approved initiative design.md needs expert stress-testing before epic 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 strengthen strategy, challenge assumptions, ground in codebase reality, and validate coherence. Produces a refined design.md (status REFINED) and refinement-report.md. Triggers on: "refine initiative", "review initiative design", "stress-test initiative", "challenge initiative", "expert panel for initiative", "improve initiative design", "polish initiative before epics". |
| user-invocable | true |
| allowed-tools | ["Read","Edit","Write","Glob","Grep","Bash","Agent","AskUserQuestion"] |
Initiative Refine
Stress-test an approved initiative design through a 5-expert refinement panel running a configurable
number of iterations (default 2, up to 5 via --iterations N) before committing to individual epic
brainstorming. Each iteration narrows focus — from strategic alignment down to final coherence —
producing a battle-tested design.md and an audit trail.
Invocation
/agile:initiative:refine @agile/initiatives/001-name/design.md — Target specific design/agile:initiative:refine 001 — Target by initiative number/agile:initiative:refine — Auto-detect (looks for APPROVED initiatives)/agile:initiative:refine --iterations 3 001 — Override iteration count (default 2, range 1-5)/agile:initiative:refine --iterations 1 @agile/initiatives/001-name/design.md — Quick single-pass review/agile:initiative:refine --iterations 5 001 — Full-depth refinement (legacy 5-iteration behavior)
The --iterations N flag can appear anywhere in the arguments; the rest of the input is parsed as
the initiative 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 initiatives: !
ls agile/initiatives/ 2>/dev/null | sort | tail -5
Hard Gate
Do NOT modify any initiative design.md until ALL iterations complete (or user stops early) AND the
user gives final approval. Do NOT invoke epic brainstorm or any implementation skill. This skill
refines — it does not advance the pipeline.
Workflow Overview
design.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
↓
design.md [REFINED] + refinement-report.md
Phase 0: Entry & Validation
0.1 Parse Iteration Count
Before resolving the initiative 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 [INIT_DIR]."
This flag value is referenced as TOTAL_ITERATIONS throughout Phase 1-3.
0.2 Resolve Initiative Path
Resolve the remaining (flag-stripped) $ARGUMENTS to INIT_DIR using this priority chain:
- If argument starts with
@ or contains /: use as file path, derive directory
- If argument is a 3-digit number (e.g.,
001): search agile/initiatives/ for matching directory
- If no argument: scan
agile/initiatives/ for directories where design.md has **Status**: APPROVED
- If exactly one candidate → use it. Multiple →
AskUserQuestion to choose. None → error and stop.
0.3 Validate Prerequisites
| Check | Requirement | Error if Missing |
|---|
design.md exists | File at INIT_DIR/design.md | "No design.md found. Run /agile:initiative:brainstorm first" |
| Status is APPROVED | **Status**: APPROVED in header | "Design status is [X], not APPROVED. Only approved designs can be refined" |
0.4 Load Context
- Read full
design.md — this becomes CURRENT_DRAFT
- Extract section headers for the locking mechanism
- Initialize state:
LOCKED_SECTIONS = []ITERATION = 0CHANGE_LOG = []
0.5 Identify Design Sections
The design.md template has these canonical sections (used for locking):
| Section ID | Section Name |
|---|
strategic-context | Strategic Context |
success-criteria | Success Criteria |
out-of-scope | Out of Scope |
approach | Approach (Options Considered + Chosen Approach) |
epic-candidates | Epic Candidates (the core table) |
timeline | Timeline |
risks-coordination | Risks & Coordination |
cross-domain-process-map | Cross-Domain Process Map |
open-questions | Open Questions |
traceability | Traceability |
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 | Strategic alignment, business case, success criteria | All equal |
| D2 | Epic decomposition, scope boundaries, grouping, cross-domain process flow validation | All equal |
| D3 | Technical feasibility, codebase reality | Grounder leads |
| D4 | Risk assessment, timeline realism | Critic + Challenger lead |
| D5 | Final coherence, completeness, polish | Reviewer leads synthesis |
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 |
Dispatch Pattern Rules
The dispatch pattern for each iteration is derived from the domains it covers:
- If the iteration covers only D1 and/or D2: launch all 5 agents in parallel
- If the iteration covers D3 (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 D4 but NOT D3: launch Critic + Challenger first. When they return,
include their findings for the remaining 3 agents, then launch those 3 in parallel.
- If the iteration covers D5 only: launch all 5 agents in parallel, with Reviewer leading the
synthesis step that follows.
- If an iteration covers D3, D4, and D5 together (as in N=2's second iteration): use the D3
rule — Grounder first, then the other 4 in parallel, and all agents explicitly address D4 and
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 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 D3):
- Also provide codebase context gathered via Glob/Grep — module listings, file counts, dependency
structures relevant to the initiative scope
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 design.md 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
Step 4: User Touchpoint
Present the iteration summary to the user via AskUserQuestion.
Summary format:
## Iteration N/TOTAL_ITERATIONS: [Focus Domain(s)]
### 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 design — commit",
"Request one more iteration on specific sections",
"Reject refinement — keep original design"]
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.
Early termination — If after any iteration ALL remaining unlocked sections receive "no issues"
from all agents, present: "All experts agree the design 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
design 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 design.md — Overwrite
INIT_DIR/design.md with CURRENT_DRAFT, changing:
**Status**: APPROVED → **Status**: REFINED- Add
**Refined**: YYYY-MM-DD (N iterations) after the Status line
- Write refinement-report.md — Create
INIT_DIR/refinement-report.md using the template at
templates/refinement-report-template.md, populated from CHANGE_LOG and iteration data.
2.3 Git Commit
git add INIT_DIR/design.md INIT_DIR/refinement-report.md
git commit -m "docs(agile): refined initiative NNN-name (N iterations)"
Phase 3: Next Steps
After committing, present:
Initiative Refined: INIT_DIR/design.md
Iterations completed: N/TOTAL_ITERATIONS
Sections refined: M
Sections unchanged: K
Refinement report: INIT_DIR/refinement-report.md
Next steps — create each epic:
/agile:epic:brainstorm @INIT_DIR/design.md
Epic candidates:
Seq 1: [name] → Sprint NNN
Seq 2: [name] → Sprint NNN
...
Do NOT invoke any downstream skill. The user decides when to proceed.
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.
- 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. Strategic first, tactical 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, better framings |
| Challenger | templates/agent-prompts/challenger.md | Hidden assumptions, failure modes, devil's advocate |
| Grounder | templates/agent-prompts/grounder.md | Codebase reality, technical feasibility, effort accuracy |
| Reviewer | templates/agent-prompts/reviewer.md | Completeness, coherence, traceability, template conformance |
| Critic | templates/agent-prompts/critic.md | Prioritization, timeline realism, risk assessment quality |
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 design.md and refinement-report.md. Do NOT invoke
epic brainstorm, implementation, or any downstream skill. The user manually proceeds.
