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. Check for a concept brief — if .beagle/concepts/<slug>/brief.md exists for this idea, ingest it and skip most of steps 2-4 (see Concept brief ingestion below)
2. Explore context — read project files, docs, git history, existing specs (lighter pass if a brief is present)
3. Assess scope — is this one spec or does it need decomposition?
4. Ask clarifying questions — one at a time, follow the thread (few to none if a brief is present)
5. Propose 2-3 directions — high-level product approaches with tradeoffs
6. Draft spec — write the structured spec document
7. Self-review — check for completeness, contradictions, implementation leakage (see references/spec-reviewer.md)
8. User review — present for approval, iterate if needed
9. Write to disk — save to .beagle/concepts/<slug>/spec.md

Brief present? ──→ Yes → Ingest brief (skip most discovery) ──┐
                ──→ No  → Explore context → Assess scope       │
                                            ├─ Too large? → Decompose → Brainstorm first sub-project
                                            └─ Right size? → Clarifying questions ─┘
                                                                                   │
Both paths converge → Propose directions → Draft spec → Self-review (fix inline) → User review
                                                                                        ├─ Changes? → Revise
                                                                                        └─ Approved? → Write to concept folder

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.

Concept brief ingestion

If the user invokes brainstorm-beagle on a concept that already has .beagle/concepts/<slug>/brief.md (produced by prfaq-beagle on pass), ingest the brief at step 1 and skip most discovery: