design-before-architecture-changes

Design before architecture changes

Brainstorming for every task is ceremony. Brainstorming for architecture changes is leverage — the cost of redoing structural work is much higher than the cost of redoing a one-file edit.

When to apply

Trigger fires if any of these is true:

• Touching more than ~2 files.
• Introducing a new module, service, package, or top-level abstraction.
• Changing a public interface (CLI flags, exported function signatures, HTTP routes, config schema).
• The user explicitly asks to "design," "plan," or "think through" the approach.

If none of these match, proceed without ceremony. Modern models handle iterative work fine; over-planning is expensive ceremony.

The process

1. Read the surrounding code. Existing patterns, conventions, nearby modules. Inherit the style; don't fight the harness.
2. Identify the constraint. What makes this hard? Performance, compatibility, an existing abstraction in the way, an unstated requirement?
3. Propose 2–3 approaches. Each one:
   • Names the trade-off in one sentence.
   • Says which files / interfaces change.
   • Says what gets simpler and what gets harder.
4. Recommend one. Don't ask the user to pick from a menu without a recommendation; that pushes the work back to them.
5. Get explicit user agreement before implementing.

Output format

A few paragraphs in conversation, not a dated doc. Long design docs become bureaucratic artifacts that nobody re-reads. The user can ask for a written doc if they want one.

Anti-patterns

• "I'll just start and we'll see." For >2-file changes, you'll spend more cleaning up the unchosen approach than you would have on the sketch.
• Brainstorming a one-line change. Time spent here is time not spent on something that mattered.
• Presenting approaches without a recommendation. You read the code; you have an opinion. Say it.
• Writing a long design doc when a paragraph would do.

Pairs with architecture-review

This skill fires before implementation; architecture-review fires after, at the end of the feature commit-set. Together they bracket the work: the design names what should be built and how it should be structured; the review checks whether what shipped matches that intent and whether the structure still holds.

Exit condition

The user has agreed to one approach. You can name the files that will change and the interface decisions you've made.