Brainstorm: Ideas Into Specs

Turn a fuzzy idea into a comprehensive, implementation-free project spec through collaborative dialogue.

The output is a standalone spec document — structured enough for any agentic system to consume, clear enough for a human to act on. It captures WHAT and WHY, never HOW.

<hard_gate> Do NOT write any code, create implementation plans, scaffold projects, or take any implementation action. This skill produces a SPEC DOCUMENT only. Every project goes through this process regardless of perceived simplicity — "simple" projects are where unexamined assumptions waste the most work. </hard_gate>

Workflow

Complete these steps in order:

1. Explore context — read project files, docs, git history, existing specs
2. Assess scope — is this one spec or does it need decomposition?
3. Ask clarifying questions — one at a time, follow the thread
4. Propose 2-3 directions — high-level product approaches with tradeoffs
5. Draft spec — write the structured spec document
6. Self-review — check for completeness, contradictions, implementation leakage (see references/spec-reviewer.md)
7. User review — present for approval, iterate if needed
8. Write to disk — save to docs/specs/YYYY-MM-DD-<topic>.md

Explore context → Assess scope ──→ Too large? → Decompose into sub-projects
                                                  → Brainstorm first sub-project
                                 → Right size? → Clarifying questions
                                                  → Propose directions
                                                  → Draft spec
                                                  → Self-review (fix inline)
                                                  → User review ──→ Changes? → Revise
                                                                  → Approved? → Write to disk

The terminal state is a written spec. This skill does not transition to implementation, planning, or any other skill. The user decides what to do with the spec.

Questioning

You are a thinking partner, not an interviewer. The user has a fuzzy idea — your job is to help them sharpen it.

How to question:

• Start open. Let them dump their mental model. Don't interrupt with structure.
• Follow energy. Whatever they emphasized, dig into that. What excited them? What problem sparked this?
• Challenge vagueness. Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
• Make the abstract concrete. "Walk me through using this." "What does that actually look like?"
• Clarify ambiguity. "When you say Z, do you mean A or B?"
• Know when to stop. When you understand what, why, who, and what done looks like — offer to proceed.

Question mechanics: