architecture-design_skill

Overview

This skill creates and validates Solution Design Documents (SDDs) focused on how a system will be built, including architecture, interfaces, and technical decisions. It produces complete sectioned SDDs, verifies consistency with requirements and codebase patterns, and generates Architecture Decision Records (ADRs) for user confirmation. The skill emphasizes documentation of implementation-ready details without performing implementation work.

How this skill works

The skill inspects product requirements and the existing codebase patterns, then drafts or completes SDD sections with concrete architecture, component boundaries, directory mappings, and interface specifications. It runs systematic validation checks—overlap/conflict detection, coverage analysis, boundary validation, and consistency verification—and surfaces trade-offs and pending ADRs for user confirmation. Outputs include a status summary, checklist results, and next steps required to finalize the SDD.

When to use it

• Creating a new solution design document from a template
• Filling or completing sections in an existing SDD
• Validating SDD completeness, consistency, and coverage against the PRD
• Designing architecture and documenting technical decisions and interfaces
• Detecting component overlap, interface conflicts, or pattern inconsistencies

Best practices

• Align every design decision to a specific PRD requirement and cite the source
• Map each component to concrete code directories and artifacts to enable implementation
• Record ADRs for implementation-impacting choices and require user confirmation
• Run overlap and boundary validation to eliminate duplicated responsibilities
• Specify measurable quality requirements and link them to test coverage

Example use cases

• Draft a full SDD for a new feature, including deployment and operational considerations
• Validate an existing SDD against updated PRD requirements and identify gaps
• Finalize API contracts and data models with clear interface specifications
• Detect and reconcile duplicated components after merging multiple design proposals
• Produce ADRs and a validation checklist to hand off to engineering for implementation