agile-initiative-refine

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:

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 [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:

1. If argument starts with @ or contains /: use as file path, derive directory
2. If argument is a 3-digit number (e.g., 001): search agile/initiatives/ for matching directory
3. If no argument: scan agile/initiatives/ for directories where design.md has **Status**: APPROVED
4. 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

1. Read full design.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 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 on
• ITERATION_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:

1. Collect findings — Parse each agent's structured output
2. Group by section — Organize findings by which design.md 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

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:

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.

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

1. 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

2. 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.