What is an SDD in this context?

An SDD (Solution Design Document) is a structured artifact that describes how the solution will be built, including architecture, interfaces, data models, and the rationale behind design decisions.

An ADR (Architecture Decision Record) captures a specific design decision, its alternatives, rationale, tradeoffs, and must be confirmed by the user before proceeding.

What happens if I decline an ADR?

If you decline a proposed ADR, the workflow pauses for re-evaluation; you can select an alternative approach, adjust tradeoffs, or request more analysis before proceeding.

specify-solution

Scanned

npx machina-cli add skill rsmdt/the-startup/specify-solution --openclaw

Files (1)

SKILL.md

5.3 KB

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.

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

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

Reference Materials

Template — SDD template structure, write to .start/specs/[NNN]-[name]/solution.md
Validation — Complete validation checklist, completion criteria
Output Format — Status report guidelines, next-step options
Output Example — Concrete example of expected output format
Examples — 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

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:

Overlap detection:

Component overlap — duplicated responsibilities?
Interface conflicts — multiple interfaces serving the same purpose?
Pattern inconsistency — conflicting architectural patterns?

Coverage analysis:

PRD coverage — all requirements addressed?
Component completeness — UI, business logic, data, integration?
Cross-cutting concerns — security, error handling, logging, performance?

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?
PRD alignment — design traces back to requirements?

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

Source

git clone https://github.com/rsmdt/the-startup/blob/main/plugins/start/skills/specify-solution/SKILL.mdView on GitHub

Overview

Specify-solution acts as a solution design specialist that crafts and validates Solution Design Documents (SDDs). It focuses on HOW the solution will be built, WHAT interfaces exist, and WHY decisions were made, aligning with PRDs and ADRs, while preserving the template structure and validation checks.

How This Skill Works

The skill reads the PRD from the specDirectory and loads the SDD template, then writes the template to specDirectory/solution.md. It guides you through exploring architectural approaches and patterns (often via parallel specialist agents) and requires user confirmation for each Architecture Decision (ADR) before progressing, ensuring traceability and thorough validation with consistency checks and overlap detection.

When to Use It

Designing system architecture and choosing patterns (monolith vs microservices, REST vs GraphQL).
Defining interfaces and API contracts between components and services.
Documenting technical decisions and tradeoffs using ADRs with rationale.
Analyzing and decomposing system components, data models, and interactions.
Working on solution.md files under .start/specs/ and ensuring alignment with PRD requirements and validation checklists.

Quick Start

Step 1: Read the PRD from specDirectory and load the SDD template (template.md).
Step 2: Write the template to specDirectory/solution.md and map requirements to the SDD sections.
Step 3: Explore architectural approaches, draft ADRs with rationale, and obtain user confirmation before committing.

Best Practices

Start from the PRD and map requirements to SDD sections before writing.
Preserve the SDD template structure and all sections exactly as defined.
Document ADRs with clear rationale, tradeoffs, and required confirmations.
Perform consistency verification and overlap detection across components and ADRs.
Wait for user confirmation on every architecture decision and pauses between cycles.

Example Use Cases

SDD for a microservices-based e-commerce platform showing ADR-1 through ADR-3 with tradeoffs and rationales.
API surface design for a payment workflow, including interface contracts and data models.
Security boundary definitions and authentication/authorization decisions documented in ADRs.
Data model and storage strategy for event-sourced architecture with consistency constraints.
Overlap analysis between service boundaries and ADRs to prevent scope creep and duplication.

Frequently Asked Questions

Add this skill to your agents