---
name: brainstorming
description: Use before any sf feature, fix, or behaviour change. Anchors the idea in the SPEC → milestone → slice → task path, checks what already exists in the codebase and memory, and produces an approved design before any code is written.
---

# Brainstorming

## Purpose

The first thinking step before code. Anchor the change in sf's planning hierarchy, find what already exists, debate with adversarial review, and emerge with an approved design that `plan-slice` or `spec-first-tdd` can act on.

If you skip this and jump to code, you risk: rebuilding what exists, missing a real consumer, locking in the wrong contract, or shipping a "professional" suggestion with no caller.

## When to Run

- A non-trivial feature or behaviour change is requested.
- A milestone is being proposed and the strategic frame is unclear.
- An upstream port has architectural ambiguity that `clarify-spec` couldn't resolve.

For trivial changes (typo fix, dependency bump, lint cleanup), skip this skill and go straight to `spec-first-tdd`.

## Skill Chain

```
← prev:  (entry point — user request, sf autonomous mode trigger, or new milestone)
→ next:  clarify-spec (if underspecified) → plan-slice → spec-first-tdd
```

Side-chain: invoke `systematic-debugging` on any bug/failure during the design process.

## What This Skill Produces

An approved design covering:

- **Purpose** — why this exists.
- **Consumer** — production code path that depends on it.
- **Contract** — observable behaviour the test will pin.
- **Implementation sketch** — where it lives, what it touches.
- **Test strategy** — what kind of test, what falsifier.
- **Evidence plan** — how we'll know it's actually working post-deploy.
- **Scope defence** — what tempting expansion this slice refuses.

## What This Skill Refuses

- Writing code, scaffolding files, or invoking implementation skills.
- Designing without first checking what already exists in sf.
- Skipping advocate/challenger on non-trivial decisions.

## Hard Gate

Do NOT advance past this skill until:

1. The idea is anchored in sf's planning hierarchy (SPEC → milestone → slice).
2. You've checked what exists — code search, memory recall, requirements scan.
3. You've identified a real production consumer.
4. A design has been presented and approved (or, in autonomous mode, satisfies the portfolio-approved envelope).

## Step 1 — Anchor in sf's Planning Hierarchy

Every change connects to a real system need. Establish:

- Which `SPEC.md` section, `REQUIREMENTS.md` Active item, or `BUILD_PLAN.md` row does this serve?
- Is there an existing milestone/slice tracking this? (`.sf/milestones/`, `.sf/active/`)
- Who is the **real consumer** — what production code path depends on this?

```bash
rg -nF "<symbol or feature name>" src/ packages/
ls .sf/milestones/ 2>/dev/null
milestone_status                              # if running inside sf
```

Search prior memory:

```
sf_search_memories(query="<topic of work>", limit=8)
```

If no consumer exists in production code, stop. There's nothing to build for nobody.

## Step 2 — Check What Already Exists

Discovery happens before design.

```bash
# Code surface
rg -nF "<feature name|symbol|route>" src/ packages/
rg -ln "<concept-keyword>" src/resources/extensions/sf/

# Sibling implementations / patterns to reuse
rg "function <similar>" src/resources/extensions/sf/

# Skill registry
ls src/resources/extensions/sf/skills/
```

Use `Explore`/`scout` subagents only when discovery legitimately fans out into 2-3 independent search angles. For one targeted question, do it inline. If the outcome might become an execution swarm later, record the natural file/directory seams and any shared-interface risk so the planner can decide safely.

Collect 2+ concrete repo facts before debate. Label:

- `Observed:` directly from code, tests, traces, or memory.
- `Inferred:` conclusion supported by observed evidence.
- `Proposed:` design choice not yet validated.

## Step 3 — Clarify (one question at a time)

If meaningful ambiguity remains, ask the highest-impact unknowns first. Multiple-choice preferred.

If many things are unclear, hand off to `clarify-spec` instead of repeatedly bouncing questions in this skill.

## Step 4 — Propose 2–3 Approaches

For each: SPEC fit, trade-offs, existing sf machinery reused. Lead with the recommended option and state why.

For non-trivial bugs / runtime fixes, name one repro/debug path before code, one after, and explain why traces alone are insufficient.

## Step 5 — Advocate and Challenger

For non-trivial decisions, run an adversarial pass via [`advisory-partner`](../advisory-partner/SKILL.md):

1. **Advocate** — strengthen the best version of the design. Argue for it.
2. **Challenger** — attack the design AND propose an alternative. A challenger anchored to the advocate's framing is not adversarial.
3. **Falsifier** (required gate, blocks Step 6): `FALSIFIER: this design is wrong if [specific observable condition]`. Generic falsifiers ("wrong if it doesn't work") are process failures.

Stop the loop when:

- The preferred design has a clear falsifier and survived it.
- The challenger objection is answered or accepted as residual risk.
- Another loop would only restate the same arguments.

This is the default for non-trivial decisions — do not ask whether to use it.

## Step 6 — Present Design

Cover: purpose, consumer, contract, implementation sketch, test strategy, evidence plan, scope defence.

When approved, persist to memory so the next session can find it:

```
log_reasoning(
  category="design-decision",
  content="design: <what> for <consumer> — approach: <key decision> — refused: <scope defence>",
  confidence=0.9
)
```

## Execution-Ready Checklist (gate to plan-slice / spec-first-tdd)

- [ ] Consumer identified — production caller named.
- [ ] Advocate + challenger done (or trivial — explicitly waived).
- [ ] Files and boundaries concrete — specific paths, not "edit the router".
- [ ] Blast radius estimated (callers count, modules touched).
- [ ] Test strategy named (test type + which behaviour the contract pins).
- [ ] Falsifier specified.
- [ ] Scope defence stated — what this slice explicitly refuses to do.

All items must pass before transitioning out of this skill.

## Key Rules

- **Purpose before artefacts** — name the consumer before naming files.
- **Prefer existing sf machinery** — `auto-loop`, `verification-gate`, `advisory-partner`, `memory-store` — over inventing new layers.
- **Runtime evidence contradicts docs → trust runtime, fix docs.**
- **YAGNI** — remove hypothetical features from every design. If three real consumers don't exist, the abstraction shouldn't either.
