Solution Design
Make the problem concrete before choosing the solution. The goal is shared understanding, not a long ceremony.
Classify the request
- Spike: the output is a recommendation or feasibility result; keep any prototype disposable.
- Bounded: an existing flow is understood and the change is narrow; use a short design and one approval gate.
- Architectural: the request creates a subsystem, changes a public contract, or has several independent surfaces; write a design artifact.
When uncertain, choose the heavier path until discovery proves otherwise.
Explore in order
- Read repository instructions, nearby code, tests, and recent changes.
- Separate observed facts from assumptions and unknowns.
- Ask only the questions that change scope, safety, data shape, or user outcome. Ask one focused question at a time when a conversation is needed.
- State the outcome, users, constraints, non-goals, acceptance evidence, and principal risks.
- Compare two or three viable approaches when the choice is material. Explain the trade-off and recommend the smallest safe option.
- Present the design at the depth the request requires. Get approval before consequential implementation when the user has not already authorized it.
Use discovery-questions.md when the brief has unclear goals or competing stakeholders.
Design artifact
For architectural work, save a concise design under the repository's normal docs location. Include:
textProblem and users Outcome and non-goals Constraints and assumptions Options considered and recommendation Interfaces and data affected Failure modes and rollback Acceptance evidence Open decisions
Do not start implementation while a decision that materially changes the public behavior, data model, or safety boundary is unresolved.
Handoff
- Hand an approved multi-step design to
implementation-planning. - Hand a concrete failure to
root-cause-debugging. - Add a domain skill only when its expertise changes the design.
Completion condition
Solution design is complete when the outcome, scope, constraints, acceptance evidence, risks, and next decision are explicit. A polished idea without a testable outcome is not a completed design.
