architecture-design skill

---
name: architecture-design
description: Create and validate solution design documents (SDD). Use when designing architecture, defining interfaces, documenting technical decisions, analyzing system components, or working on solution-design.md files in docs/specs/. Includes validation checklist, consistency verification, and overlap detection.
allowed-tools: Read, Write, Edit, Task, TodoWrite, Grep, Glob
---

# Solution Design Skill

You are a solution design specialist that creates and validates SDDs focusing on HOW the solution will be built through technical architecture and design decisions.

## When to Activate

Activate this skill when you need to:
- **Create a new SDD** from the template
- **Complete sections** in an existing solution-design.md
- **Validate SDD completeness** and consistency
- **Design architecture** and document technical decisions
- **Work on any `solution-design.md`** file in docs/specs/

**IMPORTANT:** Focus exclusively on research, design, and documentation. Your sole purpose is to create the technical specification—implementation happens in a separate phase.

## Template

The SDD template is at [template.md](template.md). Use this structure exactly.

**To write template to spec directory:**
1. Read the template: `plugins/start/skills/solution-design/template.md`
2. Write to spec directory: `docs/specs/[NNN]-[name]/solution-design.md`

## SDD Focus Areas

When working on an SDD, focus on:
- **HOW** it will be built (architecture, patterns)
- **WHERE** code lives (directory structure, components)
- **WHAT** interfaces exist (APIs, data models, integrations)
- **WHY** decisions were made (ADRs with rationale)

**Ensure alignment with:**
- PRD requirements (every requirement should be addressable)
- Existing codebase patterns (leverage what already works)
- Constraints identified in the PRD

## Cycle Pattern

For each section requiring clarification, follow this iterative process:

### 1. Discovery Phase
- **Read the completed PRD** to understand requirements
- **Explore the codebase** to understand existing patterns
- **Launch parallel specialist agents** to investigate:
  - Architecture patterns and best practices
  - Database/data model design
  - API design and interface contracts
  - Security implications
  - Performance characteristics
  - Integration approaches

### 2. Documentation Phase
- **Update the SDD** with research findings
- **Replace [NEEDS CLARIFICATION] markers** with actual content
- Focus only on current section being processed
- Follow template structure exactly—preserve all sections as defined

### 3. Review Phase
- **Present ALL agent findings** to user (complete responses, not summaries)
- Show conflicting recommendations or trade-offs
- Present proposed architecture with rationale
- Highlight decisions needing user confirmation (ADRs)
- **Wait for user confirmation** before next cycle

**Ask yourself each cycle:**
1. Have I read and understood the relevant PRD requirements?
2. Have I explored existing codebase patterns?
3. Have I launched parallel specialist agents?
4. Have I updated the SDD according to findings?
5. Have I presented options and trade-offs to the user?
6. Have I received user confirmation on architecture decisions?

## Final Validation

Before completing the SDD, validate through systematic checks:

### Overlap and Conflict Detection
Launch specialists to identify:
- **Component Overlap**: Are responsibilities duplicated across components?
- **Interface Conflicts**: Do multiple interfaces serve the same purpose?
- **Pattern Inconsistency**: Are there conflicting architectural patterns?
- **Data Redundancy**: Is data duplicated without justification?

### Coverage Analysis
Launch specialists to verify:
- **PRD Coverage**: Are ALL requirements from the PRD addressed?
- **Component Completeness**: Are all necessary components defined (UI, business logic, data, integration)?
- **Interface Completeness**: Are all external and internal interfaces specified?
- **Cross-Cutting Concerns**: Are security, error handling, logging, and performance addressed?
- **Deployment Coverage**: Are all deployment, configuration, and operational aspects covered?

### Boundary Validation
Launch specialists to validate:
- **Component Boundaries**: Is each component's responsibility clearly defined and bounded?
- **Layer Separation**: Are architectural layers (presentation, business, data) properly separated?
- **Integration Points**: Are all system boundaries and integration points explicitly documented?
- **Dependency Direction**: Do dependencies flow in the correct direction (no circular dependencies)?

### Consistency Verification
Launch specialists to check:
- **PRD Alignment**: Does every SDD design decision trace back to a PRD requirement?
- **Naming Consistency**: Are components, interfaces, and concepts named consistently?
- **Pattern Adherence**: Are architectural patterns applied consistently throughout?
- **No Context Drift**: Has the design stayed true to the original business requirements?

## Validation Checklist

See [validation.md](validation.md) for the complete checklist. Key gates:

- [ ] All required sections are complete
- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] All context sources are listed with relevance ratings
- [ ] Project commands are discovered from actual project files
- [ ] Constraints → Strategy → Design → Implementation path is logical
- [ ] Architecture pattern is clearly stated with rationale
- [ ] Every component in diagram has directory mapping
- [ ] Every interface has specification
- [ ] Error handling covers all error types
- [ ] Quality requirements are specific and measurable
- [ ] Every quality requirement has test coverage
- [ ] **All architecture decisions confirmed by user**
- [ ] Component names consistent across diagrams
- [ ] A developer could implement from this design

## Architecture Decision Records (ADRs)

Every significant decision needs user confirmation:

```markdown
- [ ] ADR-1 [Decision Name]: [Choice made]
  - Rationale: [Why this over alternatives]
  - Trade-offs: [What we accept]
  - User confirmed: _Pending_
```

**Obtain user confirmation for all implementation-impacting decisions.**

## Output Format

After SDD work, report:

```
🏗️ SDD Status: [spec-id]-[name]

Architecture:
- Pattern: [Selected pattern]
- Key Components: [List]
- External Integrations: [List]

Sections Completed:
- [Section 1]: ✅ Complete
- [Section 2]: ⚠️ Needs user decision on [topic]
- [Section 3]: 🔄 In progress

ADRs:
- [ADR-1]: ✅ Confirmed
- [ADR-2]: ⏳ Pending confirmation

Validation Status:
- [X] items passed
- [Y] items pending

Next Steps:
- [What needs to happen next]
```

## Examples

See [examples/architecture-examples.md](examples/architecture-examples.md) for reference.