Brainstorm

---
name: brainstorm
description: >-
  You MUST use this skill before /pm when work is ambiguous, scope is unclear,
  or multiple approaches exist. Explores problem space, proposes 2-3 approaches
  with trade-offs, and produces an approved spec document that feeds into both
  issue creation (/pm) and implementation planning (/cdt). Triggers: brainstorm,
  explore idea, think through, design approach, what should we build, explore
  options, weigh approaches, compare solutions, needs help deciding between
  alternatives.
user-invocable: true
argument-hint: "[topic or problem description]"
allowed-tools:
  - Read
  - Edit
  - Grep
  - Glob
  - Bash
  - AskUserQuestion
  - WebSearch
  - WebFetch
  - Write
  - Skill
metadata:
  author: claude-pm
  version: "1.0"
---

# Brainstorm: Pre-Creation Design Exploration

Explore the problem space, clarify requirements, and converge on a design direction **before** creating
issues. This skill produces a **spec document** — capturing intent, trade-offs, the chosen approach, and
enough detail for both issue creation (`/pm`) and implementation planning (`/cdt`).

## When to Use

Use this skill when:
- The work is ambiguous — user knows *what* they want but not *how*
- Multiple valid approaches exist and trade-offs need discussion
- Scope is unclear — could be one issue or an epic with sub-issues
- The problem domain is unfamiliar and needs exploration first
- A request is large enough that jumping straight to issue creation would produce a vague ticket

Do NOT use for:
- Clear, well-scoped bugs (go directly to `/pm`)
- Simple chores or dependency updates
- Work that already has a design document or spec

## Hard Gate

<HARD-GATE>
Do NOT invoke `/pm`, `/cdt`, create any GitHub issue, or take any implementation action until:
1. You have proposed approaches and the user has selected one
2. You have presented a spec document and the user has approved it

This applies to EVERY brainstorming session regardless of perceived simplicity. A spec can be
short (5-10 lines for a simple feature), but it must exist and be approved.
</HARD-GATE>

### "This Is Too Simple To Need a Spec"

No. Every brainstorming session produces a spec. The spec scales with complexity:
- Simple feature: 5-10 lines covering approach, scope, and key decisions
- Medium feature: half a page with trade-off analysis and component breakdown
- Complex initiative: full spec with architecture, decomposition, and risk assessment

The cost of a 30-second review of a short spec is negligible. The cost of a poorly scoped issue
that an agent executes in the wrong direction is significant.

## Arguments

If the user provides arguments (e.g., `/pm:brainstorm caching layer for API`), treat the entire
argument string as the **initial topic**. Use it to focus Step 1 context gathering and to skip
obvious clarifications in Step 2. If no arguments are provided, start with an open-ended discovery
in Step 2.

## Workflow

```text
1. Context → 2. Clarify → 3. Propose → 4. Converge → 5. Write Spec → 6. Self-Review → 7. User Review → 8. Transition
```

### Step 1: Explore Context

Before asking any questions, gather context silently:

1. **Project awareness**: Read the project's README, CLAUDE.md, or similar docs to understand what this project does
2. **Recent work**: If the current directory is inside a Git work tree, run `git log --oneline -20` to see recent direction. If not, skip this step silently.
3. **Relevant code**: If the user mentioned a specific area, use `Glob` and `Grep` to survey it
4. **Existing issues**: Check if `gh` is available and authenticated, then run `gh issue list --limit 10 --state open` to check for related work. If `gh` is not available or not authenticated, skip this step silently — it's informational, not blocking.
5. **Visual workflow overview**: If the `visual-explainer:generate-web-diagram` skill is available, invoke it to show the user an interactive workflow diagram — the 8 steps as a flowchart with the current step highlighted and the review loop (Step 7 → Step 5) shown as a feedback edge. This gives the user a visual map of the process they're about to go through. Skip this if visual-explainer is not installed.

**Cross-project topics.** If the user's topic is about a different project than the current working
directory (e.g., they ask about their Express API while you're in a skills marketplace repo),
acknowledge this in Step 2. You can still brainstorm effectively — use `WebSearch` to research
the domain, ask the user for relevant file paths or architecture details, and note in the spec's
"Files Affected" section that paths are assumed and should be verified. Do not fabricate file
paths you cannot confirm.

Do NOT dump this research back at the user. Use it to ask smarter questions in Step 2.

### Step 2: Clarify Intent

Ask clarifying questions to understand what the user actually wants. Follow these rules strictly:

**One question per message.** Never ask more than one question at a time. Wait for the answer before
asking the next question. This forces depth — users give better answers to focused questions than to
a wall of 5 questions at once.

**Prefer multiple choice over open-ended.** When possible, offer 2-4 concrete options rather than
asking "what do you want?" Open-ended questions get vague answers; structured choices get decisions.

**Use your context research.** Frame questions using what you learned in Step 1. Instead of "what part
of the codebase?" ask "I see the auth module uses JWT tokens in `src/auth/` — is this about the token
refresh flow or the login flow?"

**Stop when you have enough.** You need to understand:
- What problem is being solved (the "why")
- Who it's for (users, developers, ops)
- What success looks like (observable outcome)
- What's explicitly out of scope

Three to five questions is typical. Do not over-interrogate — if the user gives a rich initial
description, you may only need one or two clarifications.

### Step 3: Propose Approaches

Present 2-3 distinct approaches. For each approach, include:

1. **Name** — a short label (e.g., "Approach A: Event-driven pipeline")
2. **How it works** — 2-3 sentences describing the approach
3. **Trade-offs** — what you gain and what you give up
4. **Complexity** — rough effort level (small / medium / large)
5. **Risk** — what could go wrong or what's unknown

End with a **recommendation** — state which approach you'd pick and why. Do not be neutral. Take a
position. The user can override, but fence-sitting wastes everyone's time.

**Apply YAGNI ruthlessly.** If an approach adds flexibility "in case we need it later," flag that as
speculative complexity. Propose the simplest approach that solves the stated problem. If the user
wants extensibility, they'll ask.

**Visual comparison (optional, requires visual-explainer plugin).** If the approaches involve
architectural differences (data flow, component structure, system boundaries) and the
`visual-explainer:generate-web-diagram` skill is available, invoke it to render a side-by-side
comparison diagram. This is especially valuable for:
- Pipeline/workflow designs with different topologies
- Component architectures with different boundaries
- Data flow alternatives (push vs. pull, sync vs. async)

Do NOT generate visuals for trivial choices or when the text description is sufficient. Ask the user
first: "Would a visual comparison of these approaches help?"

Use `AskUserQuestion` to let the user pick:

```text
Question: "Which approach do you prefer?"
Options:
  - Approach A: [name] — [one-line summary]
  - Approach B: [name] — [one-line summary]
  - Approach C: [name] — [one-line summary]
  - None of these — let me describe what I want
```

### Step 4: Converge on Design

With the chosen approach, flesh out the design. Present it in sections scaled to complexity:

**For simple features (1 issue):**
- Approach summary (2-3 sentences)
- Key decisions (bullet list)
- Scope boundary (in/out)

**For medium features (2-3 issues):**
- Approach summary
- Key decisions with rationale
- Component breakdown (what pieces need to change)
- Scope boundary
- Open questions (if any remain)

**For complex initiatives (epic-level):**
- Approach summary
- Architecture overview (components, data flow, interfaces)
- Decomposition into work units (each becomes an issue)
- Dependencies between units
- Scope boundary
- Risks and mitigations
- Open questions

**Codebase exploration.** Before presenting the design, explore the codebase for the chosen approach:

1. Use `Glob` and `Grep` to find files that will need modification
2. Use `Read` to understand existing patterns, interfaces, and conventions in the affected areas
3. Check for related work: existing TODOs, tests, similar implementations
4. Record concrete file paths — these feed directly into the spec's "Files Affected" section

Do NOT present the design without grounding it in the actual codebase. An ungrounded design produces
an ungrounded spec, which produces vague issues, which agents execute poorly.

If the topic is about a different project (see Step 1 cross-project note), ask the user for
relevant file paths or architecture details instead of exploring. Mark all paths in the spec as
`[unverified — user-provided]` so downstream consumers know to check them.

**Visual architecture diagram (requires visual-explainer plugin).** For medium and complex work, if
`visual-explainer:generate-web-diagram` is available, generate an architecture diagram showing
component boundaries, data flow, and the decomposition into work units. Present the diagram
alongside the architecture overview section. Skip if visual-explainer is not installed.

For medium and complex work, present each section and wait for the user to confirm before moving
to the next. For simple features, present the full design at once.

### Step 5: Write Spec Document

Save the approved design to a file:

```bash
# Ensure the directory exists
mkdir -p .dev/pm/specs
```

**File path:** `.dev/pm/specs/$(date +%Y-%m-%d)-<topic-slug>.md`

Use the `date` command to resolve the date — do not hardcode or guess the current date.

**Before writing, determine the complexity tier.** This controls which sections to include:

| Tier | Criteria | Sections to include |
|------|----------|-------------------|
| **Simple** (1 issue) | Single component, no structural changes | Problem, Chosen Approach (no Alternatives table), Key Decisions, Scope, Technical Design (2-3 sentences), Files Affected, Open Questions |
| **Medium** (2-3 issues) | Multiple components or interfaces | All sections, each concise |
| **Complex** (epic) | 3+ work units, cross-cutting concerns | All sections fully fleshed out, architecture diagram referenced |

Omit sections that don't apply to the tier. A simple spec with an Alternatives Considered table
and Work Breakdown is over-engineered — it signals the tier was misclassified or the template
was filled in mechanically without thinking about what the reader needs.

**Spec template** (include only the sections appropriate for the tier):

```markdown
# Spec: <Topic>

**Date:** YYYY-MM-DD
**Status:** Draft

## Problem

<What problem are we solving and why — include the user/stakeholder perspective>

## Chosen Approach

**<Approach name>**

<2-3 paragraph description of the approach, how it works, and why it was chosen over alternatives>

### Alternatives Considered
<!-- MEDIUM and COMPLEX only — omit for SIMPLE -->

| Approach | Pros | Cons | Why not |
|----------|------|------|---------|
| <Alt 1> | <pros> | <cons> | <reason rejected> |
| <Alt 2> | <pros> | <cons> | <reason rejected> |

### Key Decisions

- <Decision 1>: <chosen option> — <rationale>
- <Decision 2>: <chosen option> — <rationale>

### Trade-offs Accepted
<!-- MEDIUM and COMPLEX only — omit for SIMPLE -->

- <What we're giving up and why that's acceptable>

## Scope

**In scope:**
- <item>

**Out of scope:**
- <item>

## Technical Design

<SIMPLE: 2-3 sentences on the approach>
<MEDIUM: component breakdown with interfaces>
<COMPLEX: architecture overview, data flow, key interfaces>

### Files Affected

<List real file paths found during codebase exploration, or "New files" for greenfield>

- `src/path/to/file.ts` — <what changes>

## Work Breakdown
<!-- MEDIUM and COMPLEX only — omit for SIMPLE -->

1. <Unit 1> — <what it does, rough size> [no dependencies]
2. <Unit 2> — <what it does, rough size> [depends on: 1]

## Open Questions

<Any unresolved items — or "None" if fully resolved>
```

Do NOT commit yet — the self-review and user review may require changes.

### Step 6: Self-Review

Before presenting the spec to the user, review it yourself. Check for:

- **Placeholders**: Any "TBD", "TODO", or vague hand-waving? Replace with specifics or mark as
  `[NEEDS CLARIFICATION: question]`
- **Contradictions**: Does the scope say X is out but the work breakdown includes it?
- **Missing rationale**: Every key decision should have a "why" — if one doesn't, add it
- **Scope creep**: Does the work breakdown include items the user didn't ask for? Remove them
- **Feasibility gaps**: Does the approach assume something about the codebase that you haven't
  verified? Use `Grep`/`Read` to confirm
- **File path accuracy**: Do the files listed in "Files Affected" actually exist? Verify with `Glob`.
  Skip this check for cross-project paths marked `[unverified — user-provided]`

Fix any issues found inline before proceeding.

### Step 7: User Review

Present the final spec to the user. Show:
- The topic and chosen approach (one-liner)
- Key decisions summary
- Scope summary
- Work breakdown (if applicable)

Ask explicitly: **"Spec looks good — approve to proceed, or want changes?"**

If the user requests changes, revise the spec (go back to Step 5), run Step 6 self-review again,
and re-present. Loop until approved. Once approved, update the spec's `**Status:**` from `Draft`
to `Approved`.

### Step 8: Transition

Once approved, present the next steps. The spec at `.dev/pm/specs/YYYY-MM-DD-<topic-slug>.md` is
designed to feed into two downstream workflows:

**Path A: Issue creation (`/pm`)**
> Create structured GitHub issues from the spec. The work breakdown maps directly to issues.

**Path B: Implementation planning (`/cdt:plan-task`)**
> Skip issue creation and go straight to an implementation plan. Invoke with the spec path as
> context (e.g., `/cdt:plan-task implement the spec at .dev/pm/specs/YYYY-MM-DD-topic.md`).
> CDT's architect teammate will use the spec as input.

**Path C: Both**
> Create issues first (`/pm`), then plan implementation for the top-priority issue (`/cdt`).

Use `AskUserQuestion` to let the user choose:

```text
Question: "Spec approved. What's next?"
Options:
  - Create issues (/pm) — turn the spec into GitHub issues
  - Plan implementation (/cdt:plan-task) — go straight to implementation planning
  - Both — create issues first, then plan the first one
  - Done for now — I'll come back to this later
```

If `AskUserQuestion` returns an empty answer, re-ask — do not assume a default. The user must
explicitly choose.

**Act on the user's choice immediately. When the table tells you to invoke `pm:pm`
(Create issues, Both), call the `Skill` tool directly — do not ask the user to re-type `/pm`.
When the table tells you to tell the user a `/cdt:plan-task` command (Plan implementation, and
the Both follow-up), print the exact command with the concrete spec filepath written in Step 5
substituted for `<spec-path>` — never echo the placeholder verbatim.**

| User choice | Action |
|-------------|--------|
| Create issues (/pm) | Invoke `pm:pm` via the `Skill` tool with no arguments. `pm` will auto-detect the just-approved spec in `.dev/pm/specs/` and skip its own ambiguity check. |
| Both | Invoke `pm:pm` via the `Skill` tool now. After `pm` returns, tell the user that the next step is `/cdt:plan-task <spec-path>` (substitute the concrete Step 5 filepath; never echo `<spec-path>` literally) for implementation planning. Do not auto-invoke cross-plugin `cdt` — leave that to the user. |
| Plan implementation (/cdt:plan-task) | Tell the user the exact command to run: `/cdt:plan-task implement the spec at <spec-path>`. (Do not auto-invoke `cdt`; it lives in a separate plugin and may need user-shaped framing.) |
| Done for now | Confirm the spec path is saved at `<spec-path>` and end the session. |

The hard gate at the top of this skill still applies: never invoke `/pm`, `/cdt`, or any
implementation tool **before** Step 7 approval. After approval, however, the user's chosen path
is binding and should be executed without forcing a manual re-invocation.

## Principles

- Ask one focused question rather than multiple shallow ones — depth produces better answers
  because users give more thought to a single question than to a wall of five
- Recommend a specific approach rather than listing neutral options — fence-sitting wastes the
  user's decision energy and signals you don't have an opinion
- Remove speculative features from every design. If the user says "might need X later,"
  acknowledge it and leave it out unless there is a concrete use case now
- Scale the spec to match the work — a simple feature gets a 10-line spec, not a 2-page design
  doc. Oversized specs for small work signal cargo-culting, not rigor
- Treat the approved spec as the contract for downstream workflows. Do not re-litigate decisions
  that were already made during brainstorming
- Generate diagrams only when they clarify something text cannot — a bullet list of 3 components
  does not need an architecture diagram