solution-design

Solution design documents (SDDs) formalize your architecture, interfaces, and design decisions without implementing code. Start by copying the official SDD template to `docs/specs/solution-design.md`, then fill sections covering how the solution builds, where code resides, what interfaces exist, and why decisions were made, including ADRs and validation checklists.

An SDD documents architecture, interfaces, and design patterns to satisfy functional requirements. Include sections on how the solution will be built, code location, interface definitions, architectural decisions with ADRs, design-pattern choices, cross-cutting concerns, and validation checklists aligned with product requirements and constraints.

Solution design validation checks completeness against the SDD template and detects overlaps between sections. Validate that architecture decisions, interfaces, and design patterns align with PRD constraints, all ADRs are documented with rationale, and cross-cutting concerns are addressed consistently across the design.

Solution design documents work for both new features and updates to existing architectures. You can create a complete SDD from the template for new work, or update specific sections in existing docs to refine architecture, interfaces, or decisions as requirements evolve.

ADRs (Architecture Decision Records) are part of your solution design document, not separate from it. Include ADRs within your SDD to document the rationale, alternatives considered, and consequences of each significant architectural decision, supporting the overall design narrative.

A solution design document describes HOW architecture will be built, WHERE code resides, WHAT interfaces exist, and WHY decisions were made—without writing implementation code. It focuses on design, patterns, and decisions; implementation follows after SDD validation and approval.