Technical Design

Make consequential implementation choices reviewable without turning the design into a coding recipe.

Decide whether design is warranted

First identify the concrete technical questions still unresolved after reading the specification and repository conventions. A question warrants design only when it cannot safely be left to implementation-time judgment and it involves:

• architecture, module responsibilities, interfaces, or seams;
• data ownership, persistence shape, state transitions, or event flow;
• a non-trivial algorithm or protocol;
• concurrency, consistency, security, privacy, performance, or operational behavior;
• integration contracts or testing seams that shape the solution;
• genuine technical alternatives with different long-term consequences.

A question is material when plausible approaches have meaningfully different consequences, or when the choice establishes a non-obvious invariant, ownership boundary, data contract, lifecycle, concurrency model, migration rule, security boundary, or operational constraint. Feature size, a missing design file, or merely touching data, state, security, or multiple modules is not sufficient evidence.

Create a design artifact only after at least one concrete question passes this materiality gate. If the specification and repository practice already determine the approach and only mechanically derivable implementation remains, report that a concise approach preview is sufficient and stop. Create neither a design artifact nor a skipped-design marker. Do not begin implementation unless the user's current request separately assigns that exact Feature or Task.