brainstorm-spec

A lightweight gate for ad-hoc development work: agree on the approach before writing code. The output is a short spec the developer approved, not a formal document.

Where this fits

Surface	For	Weight
Full PRD → Design Doc	Product features that R&D builds	Heavy — the prd-writer / product pipeline
draft-proposal	An infra/process idea for triage	Medium — a docs/proposals/ file
brainstorm-spec (here)	An ad-hoc coding task with no PRD, but non-trivial design choices	Light — a spec in-conversation or a scratch file
Just code it	A one-liner, a typo, obvious wiring	None

Use this when the task is too small for a PRD but too consequential to code blind — a refactor with choices, a new endpoint with contract decisions, a bug fix that could go several ways.

The gate

Do not write production code until the developer has approved a spec. Brainstorming produces options and a recommendation; the developer picks. Then, and only then, code.

The loop

1. Understand the intent

Ask what problem is being solved and what "done" looks like. If the request is vague ("make search better"), converge on a concrete, testable goal before proposing anything. One or two focused questions — not a survey.

2. Surface the real choices

Identify the 2-3 decisions that actually branch the implementation:

• Data shape / contract (what does the API return? does it break a consumer?).
• Where the logic lives (which service? gateway orchestrator vs service layer?).
• Trade-offs (simple-now vs extensible, read-time vs write-time cost).

For each, give a recommendation with a reason, not an exhaustive menu. The developer is choosing, not researching.

3. Write the spec

A few lines the developer can approve or amend:

## Spec: <task>

**Goal:** <one line, testable>
**Approach:** <the chosen design>
**Contract impact:** <DTOs/RPC/consumers touched, or "none">
**Out of scope:** <what this deliberately does not do>
**Verification:** <how we'll know it works>

Keep it in the conversation for small tasks; write it to a scratch file for anything spanning multiple sessions (so it survives context compaction).

4. Get explicit approval

Present the spec and wait for a clear "yes" (or amendments). Do not infer approval from silence. Ambiguous response → ask.

5. Hand off to implementation

Once approved:

• If it's several units of work → breakdown into issues.
• If it involves non-trivial logic → drive it via test-driven-development.
• If it touches a specialized domain (auth, payments, data, contracts) → loop in the owning agent.

Red-flags table

Rationalization	The discipline
"I basically know what to build, let me start"	If there are branching design choices, write the 5-line spec and confirm first.
"I'll present all the options I can think of"	2-3 real choices, each with a recommendation. Not a survey.
"They didn't object, so I'll proceed"	Silence is not approval. Ask for an explicit yes.
"This needs a full PRD"	If R&D will build it as a product feature, yes — hand to prd-writer. If it's a dev task, this lighter gate is enough.
"Let me just refactor as I go and design emerges"	Design-then-code. Emergent design on a consequential change is how scope and contracts drift.

Token note

Brainstorming is reasoning, not I/O — it belongs in the main thread. But if converging requires reading large parts of the codebase, scope the reads (name the files) or delegate the exploration to an Explore subagent per delegate-heavy-context, and bring back only the findings that inform the choice.