brainstorm

# Brainstorm

Guide the user through a structured design conversation that produces a written, approved spec before any implementation begins. The output is a persistent file in the project that feeds into Claude Code plan mode and then into `/optimus:tdd` for test-first implementation.

### The Hard Gate

**No implementation until the design is approved.** Do not invoke any implementation skill, write any production code, scaffold any project structure, or take any implementation action until you have written a spec and the user has approved it. This applies to all tasks — even seemingly simple ones. Unexamined assumptions in "simple" projects cause the most wasted effort.

## Step 1: Pre-flight

Read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` for workspace detection. If a multi-repo workspace is detected, process within the repo the user is targeting. If ambiguous, ask which repo.

### Verify prerequisites

Check that `.claude/CLAUDE.md` exists. If it doesn't, stop and recommend running `/optimus:init` first — project context and coding guidelines shape design decisions.

Load these documents:

| Document | Role |
|----------|------|
| `.claude/CLAUDE.md` | Project overview, tech stack, architecture |
| `coding-guidelines.md` | Quality standards that constrain the design |
| `docs/product/product-context.md` *(if present)* | Product vision — steering context |
| `docs/product/mvp-prd.md` *(if present)* | MVP scope — steering context |
| `docs/product/tech-stack.md` *(if present)* | Target tech stack — steering context |

The three `docs/` rows are the optional spec-driven-development steering cascade (scaffolded by `/optimus:spec-init`). Load them **only if they exist**, and treat them as higher-altitude direction that *informs* the design — never as the task itself or as content to copy. The spec you write stays engineering-focused: do **not** author product/PM prose (personas, KPIs, business-value) into it. See `$CLAUDE_PLUGIN_ROOT/references/sdd-mapping.md` for the precedence contract.

**Monorepo path note:** Read the "Monorepo Scoping Rule" section of `$CLAUDE_PLUGIN_ROOT/skills/init/references/constraint-doc-loading.md` for doc layout and scoping rules.

### Scan project structure

Explore the project's directory structure, key modules, and existing patterns. This grounds the design conversation in what actually exists — not assumptions.

## Step 2: Gather Intent

### JIRA context detection

Before asking the user for input, check for pre-existing JIRA context:

1. If the user's inline input matches a JIRA key pattern (`[A-Z][A-Z0-9]+-\d+`), check for `docs/jira/<key>.md`. If found, read it and use its Goal and Acceptance Criteria as the brainstorm input. If the file is not found, inform the user ("No task file found for [KEY] — run `/optimus:jira [KEY]` first to fetch it") and proceed with normal intent gathering below.

2. If no inline input (or no JIRA key match), check whether `docs/jira/` exists and contains `.md` files. If so, read each file's YAML frontmatter and select the one with the most recent `date` field. Extract the `issue` field and the Goal section. Present to the user via `AskUserQuestion` — header "JIRA context", question "Found JIRA context: [ISSUE-KEY] — [Goal]. Use this as the basis for design?":
   - **Use it** — "Design around this JIRA task"
   - **Ignore** — "Describe a different task"

   If the file's `date` frontmatter field is older than 7 days, add a note: "(This context is [N] days old — you may want to re-run `/optimus:jira` for fresh data.)"

   If **Use it**: use the file's Goal and Acceptance Criteria as the brainstorm input. Proceed to clarifying questions (skip the intent-gathering prompts below).
   If **Ignore**: proceed with normal intent gathering below.

3. If no `docs/jira/` directory or no files in it, proceed with normal intent gathering below.

### Gather from user

If the user provided a description inline (e.g., `/optimus:brainstorm "add authentication system"`), use it. Otherwise, use `AskUserQuestion` — header "Design scope", question "What do you want to build or change?":
- **New feature** — "Build something new (e.g., 'Add user authentication')"
- **Significant change** — "Rework or extend an existing part of the system"

If the description is longer than ~3 sentences (e.g., a pasted spec, ticket, or acceptance criteria), distill it into a **single-sentence goal** and confirm with `AskUserQuestion` — header "Distilled goal", question "I've distilled your input to: '[single-sentence summary]'. Is this accurate?":
- **Looks good** — "Proceed with this goal"
- **Adjust** — "Let me refine the focus"

### Clarifying questions

Before asking questions, identify your key assumptions about scope, constraints, and expected behavior. Surface them in your reply text before the first `AskUserQuestion` call so the user can correct or confirm them.

Ask up to **3 clarifying questions** to fill critical gaps — one per `AskUserQuestion` call, prefer multiple-choice options. Focus on:
- Constraints the user hasn't mentioned (performance, compatibility, security)
- Scope boundaries (what's in, what's explicitly out)
- Integration points with existing code

Skip questions if the intent is already clear. Three is the maximum, not the target.

## Step 3: Explore and Propose

### Explore relevant code

Based on the user's goal, explore the codebase areas that the design will touch:
- Existing modules, patterns, and conventions relevant to the goal
- Dependencies and integration points
- Related tests (if any) that reveal expected behavior

### Propose approaches

Present **2-3 approaches** to the user:

```
## Approaches

### A: [Name]
[Brief description — 2-3 sentences]
- **Pros:** [key advantages]
- **Cons:** [key disadvantages]
- **Effort:** [Low / Medium / High]
- **Alignment:** [how well it fits existing patterns]

### B: [Name]
...

### C: [Name] (optional — only if genuinely distinct)
...

**Recommendation:** [Appr