Design Before Code

In one line: No code until a design exists — brainstorm → spec → plan → execute.

Do this: For any change you cannot fully hold in your head, write the design first. The 30-60 minutes it costs is cheaper than the rework it prevents.

What: Every non-trivial change follows a mandatory pipeline: brainstorm (explore the problem space) → design specification (commit to an approach with rationale) → implementation plan (decompose into ordered tasks) → execution. No code is written until a design exists.

Why: AI code generation is fast — that is both its strength and its primary risk. Without a design phase, development degenerates into producing plausible code quickly, reviewing it superficially, and committing it, only to rework it when integration reveals the wrong approach, misunderstood scope, or unconsidered edge cases.

Working code can still solve the wrong problem or break downstream assumptions. Articulating the problem, alternatives and approved outcomes before implementation helps expose those risks; it does not eliminate them. Business validation and independent acceptance remain necessary.

The design also supplies AI context: it makes constraints and expected behavior available before implementation. Evaluate alignment against those expectations; a supplied specification does not guarantee a correct first attempt.

Evidence: The Brainstorm Gate (Section 3.1) asks for a design artifact addressing the Decision-Cost Rubric. No detector enforces it — §14 records the mechanism as none (human-asserted). A missing Pre-Mortem Block is a person noticing an absence, not a gate firing.

How: The Superpowers plugin provides two skills that govern this pipeline:

1. brainstorming — Structured problem exploration. Produces a problem statement, constraint analysis, and 3+ candidate approaches with tradeoffs. Output is a conversation, not a document. Its purpose is to prevent premature commitment to the first approach that seems reasonable.

2. writing-plans — Converts brainstorm output into a single design artifact: a formal specification plus an ordered implementation task list. Uses the project's design doc template (audience, problem statement, design decisions table, data flow, API contracts, error handling, testing strategy). Each task specifies inputs, outputs, acceptance criteria, and estimated complexity, sized to be completable in a single agent session (typically 15-60 minutes of implementation). The artifact is committed to docs/ before any implementation begins.

Trivial editorial changes may use a short design note. Judge impact, not line count: approval authority, access, business meaning, safety, external effects and in-flight behaviour are non-trivial even when changed through one configuration value.

For deeper treatment of ADR practices, see appendix-g-adr.md.

---