# Brainstorm — process, not archive

A Claude Code skill that is a **thinking partner for designing large-scale software changes**.
The session's product is the repo's living documentation: the conversation helps the user think
correctly, the record stays readable at any pause, and the session ends with a harvest so
complete that the session folder is useless — it moves to history and the user deletes or
commits it.

> Spec (single source of truth): `docs/skills/brainstorm/` in the etna repo. The etna
> copy of this skill (`skills/brainstorm/`) is canonical; the user-level path
> `~/.claude/skills/brainstorm/` is a symlink to it.

## The architecture — one capability, two seats

Prose obligations decay in the conversing seat: the fleet audit behind v3 found the same rules
dying in every real session, even the successful ones. So the capability is split:

| Seat | Component | Owns |
| --- | --- | --- |
| Conversation (main loop) | `SKILL.md` — the facilitator | The dialogue, the basis gate, the moves, one write: appending everything to `ops/capture.md` |
| Paper (dispatched agent) | `agents/brainstorm.md` — the twin, pinned strong tier | Every working-surface file: distilling ops into pillars, recomposing the thesis whole, the semantic audits, the harvest |
| Integrity (script) | `scripts/detector.mjs` | Mechanical checks with stable rule IDs; blocks the manifest and the move while gates fail |
| Quality (authoring-time) | `evals/` (never ships) | Session-replay scenarios, the two-agent audit, contrastive facilitation |

Every twin dispatch is paired-logged in `ops/sync-log.md` — the facilitator writes the dispatch
line, the twin writes the result — so reconciliation is observable, never asserted.

## The session lifecycle

```
/brainstorm start
  → basis gate (a document, an old session folder of any format, or a brain dump)
  → bootstrap docs/research/{topic}-brainstorm/ (ops/ untracked; twin writes the surface)
  → converse: dump / interview / probe / blindspot / converge — steerable in plain language
  → "let me read" anytime: compose on demand, read the thesis, come back
/brainstorm stop
  → converge → manifest → ONE user approval → apply → uselessness test
  → folder moves to docs/history/brainstorms/{topic}/ (the completion marker)
  → the user decides: delete or commit
```

The working surface: `thesis.md` (claim → argument → what changed, recomposed whole, stamped),
`forks.md` (open questions with close conditions — the only convergence currency), `ledger.md`
(commitments: Decision / Why / How to apply / Resolves, declined options inline with re-evaluate
conditions), `state.md` (anchor + the aspect map), `basis/`, `fragments/` (harvest-native,
drafted in destination format), and untracked `ops/` (raw capture + sync log; deleted at stop).

## Files

- `SKILL.md` — the facilitator hub
- `references/doctrine.md` — thesis / forces / forks / commitments / consequences epistemics
- `references/session-schema.md` — the single format authority (what the detector enforces)
- `references/harvest.md` — the stop pipeline and routing map
- `scripts/detector.mjs` — the rule registry (`node detector.mjs <folder> [--gate=…] [--json]`)
- `scripts/fixtures/` — contrastive fixtures + runner (authoring-time; never ships)
- `evals/` — session-replay + audit harness (authoring-time; never ships)