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

1. Read repository instructions, nearby code, tests, and recent changes.
2. Separate observed facts from assumptions and unknowns.
3. 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.
4. State the outcome, users, constraints, non-goals, acceptance evidence, and principal risks.
5. Compare two or three viable approaches when the choice is material. Explain the trade-off and recommend the smallest safe option.
6. 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:

Problem 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.