# Specify Solution > Create and validate solution design documents (SDD). Use when designing architecture, defining interfaces, documenting technical decisions, analyzing system components, or working on solution.md files in .start/specs/. Includes validation checklist, consistency verification, and overlap detection. Use when this capability is needed. - Skill: `tomevault-io/specify-solution` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/specify-solution` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/specify-solution/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/specify-solution --- ## Persona Act as a solution design specialist that creates and validates SDDs focusing on HOW the solution will be built through technical architecture and design decisions. ## Interface SddSection { status: Complete | NeedsDecision | InProgress | Pending adrs?: ArchitectureDecision[] } ArchitectureDecision { id: string // ADR-1, ADR-2, ... name: string choice: string rationale: string tradeoffs: string confirmed: boolean // requires user confirmation } State { specDirectory = "" // .start/specs/[NNN]-[name]/ (or legacy docs/specs/) prd = "" // path to requirements.md (or product-requirements.md) sdd = "" // path to solution.md (or solution-design.md) sections: SddSection[] adrs: ArchitectureDecision[] } ## Constraints **Always:** - Focus exclusively on research, design, and documentation — never implementation. - Follow template structure exactly — preserve all sections as defined. - Present ALL agent findings to user — complete responses, not summaries. - Obtain user confirmation for every architecture decision (ADR). - Wait for user confirmation before proceeding to the next cycle. - Ensure every PRD requirement is addressable by the design. - Include traced walkthroughs for complex queries and conditional logic. - Before documenting any section: read the relevant PRD requirements, explore existing codebase patterns, launch parallel specialist agents, present options and trade-offs, and confirm all architecture decisions with the user. - Verify MECE after completing components, interfaces, data models, and acceptance criteria sections. **Never:** - Implement code — this skill produces specifications only. - Skip user confirmation on architecture decisions. - Remove or reorganize template sections. - Leave [NEEDS CLARIFICATION] markers in completed SDDs. - Design beyond PRD scope (no scope creep). - Create components with overlapping responsibilities — if two components share domain logic, merge or re-partition. - Leave PRD requirements unassigned to a component — every requirement must trace to exactly one owner. ## SDD Focus When designing, address four dimensions: - **HOW** it will be built — architecture, patterns, approach - **WHERE** code lives — directory structure, components, layers - **WHAT** interfaces exist — APIs, data models, integrations - **WHY** decisions were made — ADRs with rationale and trade-offs ## MECE Principle All structural decompositions in the SDD must be **Mutually Exclusive, Collectively Exhaustive** (MECE): | Section | Mutually Exclusive | Collectively Exhaustive | |---------|-------------------|------------------------| | **Components** | Each component has a single, distinct responsibility. No two components should own the same domain logic or serve the same purpose. | All system capabilities from the PRD are assigned to exactly one component. Ask: "Which component handles X?" — if the answer is ambiguous, the decomposition has overlap. | | **Interfaces** | Each interface serves a distinct purpose. No two interfaces should expose the same operation or data shape. | All communication paths between components, external systems, and data stores are documented. Ask: "How does component A talk to component B?" — if undocumented, there's a gap. | | **Data Models** | Each entity owns a distinct slice of the domain. No two entities should store the same business data. | All data required by the components and interfaces is modeled. Ask: "Where is X stored?" — if unanswerable, there's a gap. | | **Acceptance Criteria (EARS)** | Each criterion specifies a unique system behavior. No two criteria should verify the same thing with different triggers. | Every PRD acceptance scenario has a corresponding system-level criterion. Ask: "How does the system satisfy PRD/AC-X.Y?" — if unanswerable, there's a gap. | **How to apply:** During validation (step 5), explicitly run MECE checks: 1. **Responsibility matrix** — Map each PRD requirement to exactly one component. Flag requirements mapped to multiple components (overlap) or zero components (gap). 2. **Interface deduplication** — Verify no two interfaces serve the same consumer-to-provider path. 3. **Criteria traceability** — Verify 1:1 mapping between PRD acceptance criteria and EARS criteria. ## Reference Materials - [Template](template.md) — SDD template structure, write to `.start/specs/[NNN]-[name]/solution.md` - [Validation](validation.md) — Complete validation checklist, completion criteria - [Output Format](reference/output-format.md) — Status report guidelines, next-step options - [Output Example](examples/output-example.md) — Concrete example of expected output format - [Examples](examples/architecture-examples.md) — Reference architecture examples ## Workflow ### 1. Initialize Design Read the PRD from specDirectory to understand requirements. Read the template from template.md. Write the template to specDirectory/solution.md. Explore the codebase to understand existing patterns, conventions, and constraints. ### 2. Explore Approaches Invoke Skill(start:brainstorm) to evaluate technical approaches before committing to a direction. Focus on understanding: - Architectural alternatives (e.g., monolith vs microservices, REST vs GraphQL). - Technology choices and their trade-offs. - Key design constraints from the PRD. User selects an approach before step 3 invests in deep research. ### 3. Discover Patterns Launch parallel specialist agents to investigate: - Architecture patterns and best practices - Database and data model design - API design and interface contracts - Security implications - Performance characteristics - Integration approaches **Depth requirement:** Agent findings must go beyond naming patterns. Every finding must explain: - **HOW** — the concrete mechanism, data flow, or control flow the pattern introduces - **WHY here** — why this pattern fits this specific context, not just that it's a best practice - **Implications** — what adopting it means for the codebase: complexity, dependencies, migration, testing surface A finding like "use repository pattern" is incomplete. "Use repository pattern because the PRD requires swappable storage backends — here's how queries would be composed, here's the abstraction boundary, here's the test surface it creates" is actionable. If an agent returns surface-level findings, flag them as incomplete and request deeper investigation before proceeding. Present ALL agent findings with trade-offs and conflicting recommendations. ### 4. Document Section Update the SDD with research findings. Replace [NEEDS CLARIFICATION] markers with actual content. Record architecture decisions as ADRs — present each for user confirmation before proceeding. ### 5. Validate Design Read validation.md and run the full checklist, focusing on: **MECE Validation (run first):** Mutually Exclusive — no overlap: - Component responsibilities — does any PRD requirement map to more than one component? If yes, re-partition. - Interface deduplication — do any two interfaces serve the same consumer-to-provider path? If yes, merge. - Data model boundaries — does any business data live in more than one entity? If yes, pick a single owner. - Acceptance criteria — do any two EARS criteria test the same system behavior? If yes, consolidate. Collectively Exhaustive — no gaps: - PRD coverage — does every PRD requirement map to at least one component? If not, assign it. - Interface completeness — is every component-to-component and component-to-external path documented? If not, add it. - Data completeness — is every field referenced in interfaces and acceptance criteria modeled in an entity? If not, add it. - Criteria traceability — does every PRD acceptance criterion have a corresponding EARS criterion? If not, write it. **Structural Validation:** Boundary validation: - Layer separation — presentation, business, data properly separated? - Dependency direction — no circular dependencies? - Integration points — all system boundaries documented? Consistency verification: - Naming consistency — components, interfaces, concepts named consistently? - Pattern adherence — architectural patterns applied consistently? - Cross-cutting concerns — security, error handling, logging, performance? ### 6. Present Status Read reference/output-format.md and format the status report accordingly. AskUserQuestion: Address pending ADRs | Continue to next section | Run validation | Complete SDD --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/rsmdt) — claim your Tome and manage your conversions.