iterative:brainstorming

What this skill does

# Brainstorming

Explore the problem space, scope the goal, and make directional choices through collaborative dialogue. Assess scope early and match ceremony to complexity — a bug fix exits in two exchanges, a new subsystem gets a full PRD.

## When to Use

- Before implementing any new feature or significant change
- When requirements are unclear or multiple approaches exist
- When the user hasn't fully articulated what they want
- When exploring an entirely new project or app idea

**When to skip:** Requirements are explicit, detailed, and the user knows exactly what they want. Offer to go straight to `iterative:tech-planning`.

## Key Principles

1. **Scope first** — Assess complexity from the initial message and codebase signals before asking questions. Route to the right path early.
2. **One question at a time** — Never ask multiple questions in a single message
3. **Multiple choice preferred** — Easier to answer than open-ended when natural options exist
4. **Be a thinking partner** — Don't just extract requirements. Bring ideas, suggest alternatives, challenge assumptions, explore what-ifs
5. **Directional, not detailed** — High-level technical direction is welcome. Implementation specifics belong in tech-planning
6. **Complexity-aware** — Be skeptical of unnecessary complexity, not of scope. Simple additions are fine; unnecessary abstraction is not
7. **What, not how** — Brainstorming captures WHAT to build (requirements, scope, decisions). Tech-planning captures HOW (files, architecture, implementation steps). Even in lighter paths, respect this boundary
8. **PRD is a living document** — For Full scope, the PRD is the requirements source of truth throughout the workflow. Tech planning and implementation may update it as reality reveals new constraints

## Step 1: Assess and Route

### Detect Resume

If user references an existing PRD or brainstorming topic: load the document (check both `docs/prd/` and `docs/brainstorms/` — treat PRDs and brainstorm documents synonymously), summarize current state, and let the user direct what happens next. Build on existing content, update in place.

### Check for Existing Context

- **Design direction docs.** Scan `docs/design-directions/` for design direction docs. If found, acknowledge the exploration upfront and fold the chosen direction into the conversation. A design direction narrows the exploration space but isn't a final spec. Build on what it establishes; explore what it doesn't answer. Reference the direction doc in the PRD when written; don't duplicate it.
- **Explicit requirements.** If requirements are already explicit and detailed: ask the user: A) Skip to creating a technical plan (recommended), B) Brainstorm anyway. If skipping: invoke `iterative:tech-planning` skill.

### Assess Scope

Before asking any questions, assess the scope of work from the initial message and a light codebase scan. This determines which path to follow.

1. **Light codebase scan.** Quickly explore relevant files and patterns to ground the assessment.
2. **Assess scope** based on the initial message + codebase signals:

| Scope | Description | Signals |
|-------|-------------|---------|
| **Quick** | Bug fix, config change, single-behavior tweak | 1-3 files, no architectural decisions, clear root cause or change |
| **Standard** | Small feature, bounded refactor, UI addition | Several files, a few decisions, clear scope |
| **Full** | Large feature, cross-cutting change, new subsystem | Many files, architectural choices, multiple stakeholders or flows |

3. **If scope is ambiguous:** Ask one targeted question to disambiguate, then assess.
4. **Present scope recommendation.** Lead with a brief rationale, then present the three options using the platform's interactive question tool — `AskUserQuestion` (Claude Code) or `request_user_input` (Codex) — marking the assessed scope as `(Recommended)`:
   - **Quick** — focused clarification, confirm understanding, then implement
   - **Standard** — collaborative Q&A, summarize deliverables, option for tech plan
   - **Full** — deep exploration, complete PRD, review and handoff

If the user overrides to a different scope, proceed with that scope's path.

---

## Quick Path

For bug fixes, config changes, and single-behavior tweaks. Gets out of the way fast.

**Question focus:** Inherently technical — questions about root cause, affected behavior, and edge cases are natural for bug fixes and tweaks.

### Clarify (0-2 questions)

Use your judgment. If the initial message plus codebase context gives you enough to understand the fix, ask zero questions. If something is ambiguous, ask one or two — no more.

### Confirm Understanding

State your understanding concisely:
- What the change is
- Which files are likely involved
- Edge cases or risks worth noting

Ask the user to confirm. If they correct something significant, update and re-confirm.

### Multi-step Enumeration

If the fix involves multiple discrete steps, briefly enumerate them at a high level (what to do, not how). These are deliverables, not implementation instructions — no file paths or code specifics.

### Exit

The skill is done. The user proceeds to implement based on the conversation. No documents, no formal review, no transition menu.

**If complexity emerges:** If at any point the problem turns out to be more complex than expected, suggest upgrading to Standard or Full scope. Carry forward everything discussed — don't repeat questions.

---

## Standard Path

For small features, bounded refactors, and UI additions. Enough structure to align on what to build without document ceremony.

**Question focus:** Product decisions + light technical direction. "Should pagination be client-side or server-side?" is fine. "Should we use offset or cursor pagination in the SQL query?" is tech-planning territory.

### Collaborative Q&A

1. Ask targeted questions one at a time. Focus on approach decisions, scope boundaries, and edge cases.
2. Bring ideas — suggest alternatives, challenge assumptions, explore what-ifs.
3. Typically 3-5 exchanges, but use your judgment. Move on when the approach and key decisions are clear, not at an arbitrary count.

### Optional Approach Discussion

Only if the path forward is genuinely ambiguous — present 2-3 lightweight directions (1-2 sentences each with a brief trade-off) and ask the user to pick. Skip this if there's an obvious approach.

### Summarize What We're Building

Capture the key outcomes of the conversation:
- **Goal** — what we're building and why (1-2 sentences)
- **Deliverables** — high-level list of what gets built (e.g., "add pagination to list view", "update UI with page controls", "handle empty state"). These describe WHAT, not HOW — no file paths or implementation steps
- **Key decisions** — choices made during the conversation that constrain the approach
- **Scope boundaries** — what's deliberately excluded
- **Edge cases** — what to watch for

Present this inline in the conversation. Do not create a document or commit anything.

### Exit Options

Present an interactive choice:
- **Implement directly (Recommended)** — scope is clear, go build it
- **Create a tech plan** — want a structured implementation plan before building

The skill exits after this choice. If the user chooses tech-planning, invoke `iterative:tech-planning` skill.

**If complexity emerges:** If Q&A reveals the work is larger than expected, suggest upgrading to Full scope. Carry forward all decisions and context.

---

## Full Path

For large features, cross-cutting changes, and new subsystems. Full ceremony — deep exploration, PRD, review, and structured handoff.

**Question focus:** Product-focused. High-level technical direction ("build vs buy", "real-time vs polling") is the limit. Implementation specifics belong in tech-planning.

### Map the Space (2-3 questions)

1. Explore the codebase lightly for relevant context.
2. Ask the 2-3 best questions to understand the problem space (one at a time).