---
name: brainstorming
description: Socratic ideation gate before any project work begins. Use when the user has a fuzzy idea, vague project intent, or asks "what should I build", "I'm thinking about X", "I want to make a Y" without a clear spec. Runs BEFORE /new-project, /init-project, or any code. Refuses to plan or code until the design has been refined through dialogue and written to .planning/specs/. Triggers on phrases like "brainstorm", "idea", "what about", "I'm thinking", "design", "should I", "help me figure out", "let's discuss".
---

# Brainstorming

The pre-planning gate. Before draht's GSD cycle runs, before code is scaffolded, before /new-project or /init-project, the idea has to be converged on. This skill enforces design-first discipline through dialogue.

## Hear the Problem Beneath the Ask

The user's words describe an artifact; the design must serve a need. They are rarely the same thing.

1. Separate the stated artifact ("a dashboard") from the underlying need — what decision, pain, or moment does it serve?
2. When the user names a solution, ask what it solves before refining it. Solutions stay candidates until the need is confirmed.
3. State the need back in one sentence ("so the real problem is X — right?") and get an explicit yes before proposing any approach.

*Example:* "I want an admin dashboard" → questioning reveals they check one number, once a week → a scheduled email beats the dashboard by a month of build time. *Prevents:* a polished spec for the wrong artifact.

## The Hard Gate

> Do NOT invoke any planning skill, write any code, scaffold any project, or take any implementation action until you have:
>   1. Asked clarifying questions one at a time
>   2. Proposed 2–3 approaches with trade-offs
>   3. Presented a structured design and the user has approved it
>   4. Written the design to `.planning/specs/YYYY-MM-DD-<slug>-design.md`

If the user pushes to skip ("just build it"), surface the trade-off: "I can scaffold something now, but skipping brainstorming usually means we throw out the first version. Are you sure?" If yes, proceed but make the assumption explicit in the spec.

## The Process

### 1. Explore Context

Before asking anything, read what's already on disk:
- `git log --oneline -30` — what has the user been working on recently?
- `ls -la` — what's in the project root?
- `.planning/` if it exists — is there an active project?
- `README.md`, `package.json`, any `*.md` in root — what does this codebase claim to do?

If an existing codebase is in play (extending a real project), run `draht-tools map-codebase` + `draht-tools graph-hotspots` first to ground ideation in the real structure — so brainstormed ideas don't contradict existing architecture.

Use this to ground questions in reality instead of asking things the user has already told you.

### 2. Ask Clarifying Questions — ONE at a time

Most failed projects come from rushing past ambiguity. Ask **one focused question per message**, not a long list. Wait for the answer, then ask the next.

Question categories (sequence from foundational → detailed):
- **Goal** — who is this for? what changes for them when it ships?
- **Constraints** — deadline? budget? team size? language/stack preferences?
- **Scope** — what's in v1? what's explicitly NOT in v1?
- **Success criteria** — how do we know it works? what's the demoable outcome?
- **Domain** — what are the key nouns and verbs in this space? any existing glossary?
- **Risks** — what's the scariest part of this? what would make it fail?

If the project is obviously oversized for one cycle (e.g., "I want to build a social network"), flag it explicitly and propose decomposition into a v1 / v2 / out-of-scope split.

### 3. Propose 2–3 Approaches With Trade-offs

Once you have enough context, propose multiple approaches:
- Approach A: the simplest path. What it sacrifices.
- Approach B: the most flexible. What it costs.
- (Optional) Approach C: the most ambitious. Why it's tempting and why it might be too much.

For each: list trade-offs in plain language (time, complexity, future flexibility, lock-in). Let the user pick — don't pre-pick for them.

### 4. Present the Design in Sections, Each With an Approval Gate

Once an approach is chosen, present the design **section by section**, not all at once:
1. Goal & non-goals
2. User stories / observable truths
3. Domain model (bounded contexts, key nouns)
4. Architecture sketch (components, data flow)
5. v1 scope (what ships) vs v2/out-of-scope (what doesn't)
6. Open questions / risks

After each section, ask: "Does this match what you want, or should we adjust?" Only move to the next section once the current one is approved.

### 5. Write the Spec to `.planning/specs/`

Once all sections are approved:

```
.planning/specs/YYYY-MM-DD-<topic-slug>-design.md
```

The file should include:
- Header with date and approver
- All approved sections
- Open questions section (the things you flagged but didn't resolve)
- Next step: which draht command picks this up (`/new-project` or `/init-project`)

### 6. Self-Review the Written Spec

Before handing off, attack the spec as if you were paid to kill it:
- Contradictions between sections (the goal says X, the architecture implies not-X)
- Gaps (a user story with no architectural support)
- Premature commitments (specific tech choices made before they were needed)
- Domain language drift (different names for the same thing)
- The strongest case the whole design is wrong — wrong scope, wrong user, or already solved by a simpler existing tool. Write that case and why the design survives it into the spec's Open Questions.

Report any findings to the user and update before proceeding. A spec that was never attacked has never been tested.

### 7. Hand Off

Direct the user to the next command:
- Greenfield with no codebase → `/new-project`
- Existing codebase → `/init-project`

The spec file becomes input to those commands.

## Anti-Patterns — STOP

- **Asking multiple questions in one message** — splits the user's attention, lowers answer quality
- **Pre-deciding before they've answered** — "I'll just assume you mean X" is a failure mode
- **Skipping the alternatives** — proposing only one approach hides the trade-space
- **Writing the spec before approval** — the spec records *decisions*, not *proposals*. Get the decision first.
- **Brainstorming code** — this skill is for the design, not the implementation. Resist the urge to start writing.

## Rationalization Table

| Excuse | Reality |
|--------|---------|
| "It's a simple project, no need to brainstorm" | Simple projects also have ambiguous scope. The skill is fast for simple ones. |
| "User said 'just build it'" | They'll be unhappier when the wrong thing gets built. Surface the trade-off. |
| "I already know what they want" | Verify by stating it back and getting confirmation. |
| "Let's iterate after a first draft" | A first draft in code is more expensive to throw away than a first draft on paper. |

## Output

Brainstorming ends with a written spec file in `.planning/specs/`. That file is the artifact. If no file is written, the skill did not complete.