brainstorm-beagle

# 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)
   - **Prior art check (brownfield only):** before specing a feature onto an existing codebase, run a neutral capability sweep to confirm the thing doesn't already exist (see *Prior Art Check* below). Runs regardless of whether 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 ─┘
                                                                                   │
Brownfield? ──→ Yes → Prior art check (neutral capability sweep) ─→ Already exists? ─→ surface, reshape/kill spec
            ──→ No  → skip ─────────────────────────────────────────────────────────────────────┐
                                                                                                  │
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:

1. **Read the brief.** Customer, problem, solution concept, stakes, forged decisions, and research pointers are already codified. Do not re-interview the user on these.
2. **Skim the PRFAQ reference.** Open `.beagle/concepts/<slug>/prfaq.md` for the Reasoning blocks — they explain what was challenged and why earlier decisions were made. This is context, not content to re-litigate.
3. **Open questions become your starting point.** The brief's *Open Questions* section lists what PRFAQ surfaced but did not close. These are what you ask the user about — not customer, problem, or motivation, which are already decided.
4. **Proceed to Exploring Directions.** Skip Clarifying Questions and Scope Assessment unless the brief is ambiguous about scope itself.

The brief is a context handoff, not a gate. Run your own Self-Review on the spec you produce — brainstorm-beagle remains responsible for implementation-leakage detection, requirement testability, and scope discipline regardless of how much discovery was pre-done upstream.

**When there is no brief:** proceed through steps 2-9 normally. Not every idea comes from PRFAQ.

**The brief does not exempt you from the prior art check.** A brief (or the issue behind it) frames the feature as something to build — that framing is exactly the bias the *Prior Art Check* exists to neutralize. Run the sweep even when ingesting a brief.

## Prior Art Check

This step exists because of a specific, expensive failure: drafting a spec that reinvents a capability the codebase already has. It applies whenever the idea is a feature being added to an **existing codebase** (brownfield). For greenfield ideas with no existing code, skip it.

**The failure mode it prevents:** An issue or brief frames a feature as new ("we removed the old truncation, design fresh") or simply omits that prior work exists. You — or a subagent you delegate exploration to — inherit that framing, look only where the framing points, confirm the framing, and spec a feature that duplicates code already shipped and tested. The spec then teaches the downstream planner and executor to rebuild something that exists.

**The discipline: search neutrally, independent of framing.**

1. **Run a capability-keyword sweep across the WHOLE workspace** — every crate/package/module, not just the directory the issue points at. Search for the *capability* by its likely names, synonyms, and abbreviations, not the issue's vocabulary. For a truncation feature: `grep -riE 'truncat|spill|cap|max_bytes|head_bytes|limit|trim|elide'` across all source roots. Cast wide; one matching file kills the assumption.
2. **Do not trust "this doesn't exist" claims.** Issues and briefs go stale relative to the code — someone may have built the thing after the issue was filed. The issue's "we r