# Brainstorming Before Code

For any new feature, refactor, or change scoped beyond the trivial (as a rough heuristic, anything touching more than a couple of files, or more than one module or package), present a design and get approval before writing implementation code, scaffolding files, or running generators. Quick fixes (one file, an obvious diff, no new public surface) are exempt.

## Core rules

### Rule 1: The design gate

Present a design and pause for approval before implementation.

A design covers, at minimum:

- **Goal**: one sentence.
- **Touched files / modules**: an explicit list with what changes in each.
- **Public surface**: any new types, interfaces, exported signatures, or API the change introduces.
- **Dependency direction**: confirm the change does not violate the project's layering or module-boundary rules.
- **Tests**: which existing tests cover this; which new tests are needed.
- **Migration / compatibility**: anything callers must change.
- **Risks / open questions**: at least one, even if minor.

### Rule 2: Scope of the gate

Apply the gate when:

- A new module, package, or build target is being added.
- A public type or interface is being introduced.
- A user-facing screen, view, or top-level component is being added or replaced.
- A change crosses an architectural layer or module boundary.
- An API contract or schema definition is being modified.
- A migration touches data, schema, or persistence.

**MAY skip** when:

- Single file, obvious diff, no new public surface.
- A pure rename or extract that the requester already specified.
- A bug fix where the fix is forced by a failing test.

When in doubt, present the design. The cost of pausing is low.

### Rule 3: How to present

Keep the design short enough to read in about 30 seconds.

```
Goal: <one line>

Files:
- src/foo/Bar.<ext>          (new, holds the BarClient interface)
- src/foo/BarClientLive.<ext> (new, real implementation)
- src/foo/BarClientFake.<ext> (new, test/preview double)

Public surface:
- interface BarClient { fetch(...) -> Bar }
- error type BarError { ... }

Dependencies: standard library only. No upward imports.

Tests:
- BarClientTests covers fetch happy path, decode error, network error.
- Injects the fake double.

Risks:
- Decoding from snake_case input: confirm whether a code generator is in
  play here, or if this is a hand-rolled client.

OK to proceed?
```

### Rule 4: Banned pre-approval actions

**MUST NOT**, before approval:

- Run a project initializer or any code generator.
- Create new files (other than scratch design notes).
- Edit existing source files.
- Run schema or API regeneration.
- Stage or commit anything.
- Spawn implementation subagents.

You MAY, before approval:

- Read the codebase to inform the design.
- Run searches to identify touched files.
- Run a build to confirm the current baseline compiles.

### Rule 5: After approval

Approval is for the SCOPE PRESENTED. If the implementation reveals a hidden case that changes scope:

- Stop.
- Surface the divergence.
- Get fresh approval before continuing.

Do not silently expand scope to "while I am here, I also fixed X."

## When approval is skipped

If a direct implementation command arrives without a design (e.g., "just add the new endpoint"), do the design pass anyway as a short, five-bullet message and ask once:
"OK to proceed with this, or do you want changes?"

A single confirmation is enough; no full ceremony required.

## Anti-patterns

- Jumping into code on a "small" change that turns into eight files touched.
- Presenting code as the design ("here is the diff, looks good?").
- Burying the design in a long preamble before the actual question.
- Designing in isolation without reading the existing patterns first.
- Treating silence as approval.

## Acceptance check

For a non-trivial change, the conversation or tracked design artifact MUST show,
before the first source edit: the goal, affected files, public surface, tests, and
principal risks, followed by explicit approval. Compare the timestamp or message
order with the first implementation edit. If implementation exposed a material
scope change, the record MUST also show a revised design and fresh approval before
work continued.