agile-epic-brainstorm

name	agile:epic:brainstorm
description	Turn epic ideas into approved designs through conversational brainstorming. Produces design.md in a new epic directory. Replaces the idea and prompt commands.
user-invocable	true
allowed-tools	Read, Edit, Write, Glob, Grep, Bash, Skill, WebFetch, WebSearch, TaskCreate, TaskList, TaskGet, TaskUpdate, AskUserQuestion, SlashCommand

Epic Brainstorm

Help turn ideas into fully formed designs through natural collaborative dialogue. This skill replaces the /agile:epic:idea and /agile:epic:prompt commands with a single conversational brainstorm that produces design.md in a new epic directory.

Invocation

• /agile:epic:brainstorm -- Interactive mode, asks what to build
• /agile:epic:brainstorm a loan restructuring system -- Interactive with seed description
• /agile:epic:brainstorm @agile/ideas/042.md -- File reference mode, reads file as seed

Entry Mode Detection

Parse $ARGUMENTS to determine entry mode:

Pattern	Mode	Behavior
Starts with @ or contains a file path (has / or .md)	File reference	Read the file and use its content as the brainstorm seed
Text description	Interactive with seed	Use the provided text as starting context
No argument	Interactive	Ask the user what they want to build

Hard Gate

Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.

Anti-Pattern: This Is Too Simple To Need A Design

Every project goes through this process. A todo list, a single-function utility, a config change -- all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple epics), but you MUST present it and get approval.

Phase 1: Entry

1. Detect entry mode from $ARGUMENTS
2. If file reference: verify the file exists, read its content, use as brainstorm seed. If the file does not exist, report the error and ask the user to provide a text description instead.
3. If interactive with seed: use the provided text as starting context
4. If no arguments: use AskUserQuestion to ask the user what epic they want to create (open-ended question, no predefined options)

Phase 2: Understanding

• Use AskUserQuestion for every clarifying question — this pauses execution and waits for the user's response
• One question per AskUserQuestion call — never batch multiple questions
• Prefer multiple choice: provide options via AskUserQuestion's options parameter when possible (e.g., ["Option A", "Option B", "Other — let me explain"]). Open-ended is fine when choices aren't natural.
• Focus on: purpose, constraints, success criteria, who benefits, scope boundaries
• Move to Phase 2.5 once you have clear answers on: (1) primary problem, (2) measurable success criteria, (3) who benefits, (4) scope boundaries (what's in/out), (5) major constraints

Phase 2.5: Verify Problem Exists (CRITICAL)

This phase verifies the problem being described still exists. This prevents planning epics based on outdated build logs or resolved issues.

Pre-Flight Verification Steps

1. Parse the idea for verification triggers:

• Does it reference a build log file? → Need fresh build
• Does it mention specific error counts? → Verify against current build
• Does it describe missing/broken files? → Verify file existence

2. If build/module is mentioned:

• Run fresh build: mvn clean compile -pl <module> 2>&1 | tee /tmp/brainstorm-verify.log
• Count current errors: grep -c "error:" /tmp/brainstorm-verify.log || echo "0"
• Compare to claimed errors in idea

3. If specific files are mentioned:

• Use Glob to verify each mentioned file still exists
• If files are missing, ask user for clarification

4. Report to user:

   ## Pre-Flight Verification Report
   
   | Check | Status | Details |
   |-------|--------|---------|
   | Build Status | ✅ FAIL / ✅ PASS | X errors found |
   | File Existence | ✅ FOUND / ⚠️ MISSING | X files missing |
   
   Verification complete.
   

Verification Outcomes

Outcome	Action
Build fails with errors	✅ PROCEED - Problem verified
Build passes (no errors)	⚠️ WARNING - Use AskUserQuestion with options: ["Verify scope — the problem may be resolved", "Proceed anyway — the problem exists beyond build errors", "Abort brainstorm"]
Files don't exist	⚠️ WARNING - Use AskUserQuestion to ask for clarification about the missing files.

NEVER skip verification when the idea references build errors, specific files, or module problems. This is the primary defense against planning failures like Epic 124.

Phase 3: Exploring

• Propose 2-3 different approaches with trade-offs
• Present options conversationally with your recommendation and reasoning
• Lead with your recommended option and explain why
• Use AskUserQuestion to let the user pick: provide approach names as options plus an "Other — none of these fit" option
• If the user rejects all approaches, go back to Phase 2 to clarify requirements further, then propose different options

Phase 4: Design Presentation

1. Read templates/design-template.md from this skill's directory
2. Present the design section by section, following the template structure
3. Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
4. Feature Candidates: Use 2-digit feature IDs in format NNN-XX (e.g., 121-01, 121-02). Present as a table with columns: | ID | Feature Name | Brief Description |. The NNN prefix comes from the epic number assigned in Phase 5.
5. After each section, use AskUserQuestion to check approval:
   • Options: ["Looks good — continue to next section", "Needs changes — let me explain", "Go back to a previous section"]
6. Be ready to go back and revise if the user selects "Needs changes" or "Go back"

Phase 5: Commit

1. Run scripts/next-epic-number.sh via Bash to get the next available epic number
2. Generate a kebab-case name from the Problem Statement or Technical Direction (2-4 words, descriptive)
3. Use AskUserQuestion to confirm the epic number and name: "Epic will be NNN-epic-name. Proceed?" with options ["Yes — create and commit", "Change the name", "Abort"]
4. Create agile/epics/NNN-epic-name/ directory
5. Write design.md using the template filled with approved brainstorm content (**Status**: APPROVED)
6. Commit to git with message: docs(agile): add design.md for epic NNN-epic-name

Key Principles

• One question at a time via AskUserQuestion -- Every question to the user must go through this tool to pause and wait for a response. Never just print a question as text.
• Multiple choice preferred -- Use the options parameter in AskUserQuestion whenever choices are natural. Easier for the user than typing.
• YAGNI ruthlessly -- Remove unnecessary features from all designs
• Explore alternatives -- Always propose 2-3 approaches before settling
• Incremental validation -- Present design section by section, get approval before moving on
• Be flexible -- Go back and clarify when something doesn't make sense

Scripts

Script	Purpose
scripts/next-epic-number.sh	Find next available 3-digit epic number from agile/epics/

Templates

Template	Purpose
templates/design-template.md	Skeleton structure for design.md output

Shared References

Module	Location	Purpose
Pre-Flight Verification	agile-epic-shared/verify/verify.md	Build and file verification procedures

Terminal State

The terminal state is a committed design.md. Do NOT invoke any implementation skill, brainstorming, or writing-plans skill. The user will manually invoke the next pipeline step (/agile:epic:plan).