brainstorm

name	Brainstorm
description	Interactive ideation and decision capture at any pipeline boundary. Opinionated dialogue that surfaces contradictions, gaps, and untested assumptions — not template-filling. Feeds the Furnace.
argument-hint	[feature-name] [--boundary <phase>] [--tier patch|feature|epic] [--hypothesis "<claim>"]

Brainstorm — Ideation & Decision Capture

An opinionated interactive dialogue, run at any pipeline boundary, for structured ideation and decision capture — not template-filling. It surfaces contradictions, dependencies, cost concerns, and untested assumptions through conversation.

Process

1. Deep context load (before saying anything substantive): project-state.md, the constitution, design docs, any existing spec.md, the prior brainstorm-log.md, and approvals/master.json to fix the pipeline position.
2. Open with 3–5 sharp, categorized observations, each tagged:
   • Contradiction — conflicts with an existing decision
   • Missing Piece — a gap in current thinking
   • Cost Concern — more expensive than it looks
   • Untested Assumption — taken for granted without evidence
   • Cross-Feature Dependency — touches another feature --boundary <phase> scopes the observations to the upcoming phase (e.g. --boundary micro).
3. Dialogue — challenge assumptions, propose alternatives, reference the constitution and prior decisions, flag scope creep against the spec tier. No monologues, no reflexive agreement.
4. Convergence detection — explicit ("capture this", "lock it in") or prompted once the exchange shifts from exploring to refining.
5. Capture the session record (only after explicit confirmation): create the feature branch and directory if needed, append a session block to brainstorm-log.md, commit (brainstorm: {feature}), update project-state.md.

Brainstorm log block

# Brainstorm Session: {date} — {boundary or topic}

## Observations
1. **{Category}:** {observation}

## Decisions
### {Topic}
- {Decision point}: {what was decided}    # numbered D-NNN

## Brainstorm Capture
{Insights that emerged — cross-spec observations, design improvements,
things that affect other features or future specs.}
- {Insight}

## Scope Tier
{patch|feature|epic} — {reasoning}

--tier {patch|feature|epic} sets proportional ceremony and persists to /genesis-accept.

Hypothesis Mode (--hypothesis "<falsifiable claim>")

Inverts brainstorm from divergent to convergent for technical research questions, using a Falsificationist cycle:

• Abduction — generate 3–5 competing, falsifiable hypotheses.
• Deduction — derive 2–3 checkable predictions per hypothesis.
• Induction — test predictions against evidence (codebase, docs, benchmarks, web research).

Each hypothesis ends survived / weakened / falsified; a Proof Report with the falsification record is appended to the log.

The Furnace

The furnace (.genesis/furnace.json) is the backlog of ideas and recurring findings worth keeping but not actioned now. Entries are F-NNN. Brainstorm and the audits feed it; later brainstorms read it.

In scope for the furnace: ideas too big for the current spec but too good to lose · recurring findings that suggest a structural fix (3+ occurrences → higher conviction) · research discoveries that open new possibilities · process improvements.

Not in scope: bug fixes (those are zero-tolerance findings, fixed now) · increments already in scope · vague observations without actionable shape.

{
  "id": "F-017",
  "title": "Extract shared validation into a reusable module",
  "description": "Three specs reimplemented the same input check — a shared validator would remove the duplication.",
  "conviction": 75,
  "source": "auth-feature/audit-a3",
  "status": "seed",
  "tags": ["refactor", "validation"],
  "target_spec": null,
  "created": "2026-06-10",
  "updated": "2026-06-18"
}

• In: a matching existing entry is updated (bump conviction / status); a genuinely new idea is appended as F-NNN with status: seed, source: "{feature}/{phase}", today's date.
• Out: when picked up, set target_spec to the spec that will implement it; once landed and accepted, flip status to fixed. A living triage queue, not a write-only graveyard.

Natural language triggers

- "brainstorm"
- "let's think about X"
- "ideate on this feature"
- "challenge my assumptions"