Technical Design Creator
Creates technical design documents that communicate architecture decisions, system structure, and key trade-offs. The output defines what to build and how it is structured — not how to execute the work step by step.
Core Principle: Architecture Over Implementation
Before adding any detail, ask: "If we change frameworks or libraries, does this still apply?"
- YES → include it (architectural decision)
- NO → exclude it (implementation detail)
Include: API contracts, data schemas, component diagrams, technology choices with rationale, event/log schemas, integration boundaries.
Exclude: CLI commands, code snippets, framework-specific syntax, file paths, tool-specific configuration.
The technical design must survive implementation changes. If the team migrates ORMs or rewrites a service, the design doc should remain valid.
Routing
- Define requirements →
/create-prd - Debate and decide options →
/create-rfc - Record a finalized decision →
/create-adr - Plan execution phases →
/create-implementation-plan
Document Sections
Mandatory
If the user does not provide this information, ask using AskUserQuestion.
- Header & Metadata — tech lead, team, epic/ticket link, status, dates
- Context — current state, business domain, stakeholders (2–4 paragraphs)
- Problem Statement & Motivation — specific problems with quantified impact, why now, cost of inaction
- Scope — in-scope (V1/MVP, min 3 items), out-of-scope (min 3 items), future considerations (V2+)
- Technical Solution — architecture overview with diagram (Mermaid), key components and responsibilities, data flow, API contracts, database changes
- Key Decisions & Trade-offs — decisions made, alternatives rejected, rationale
- Risks — min 3 risks with impact (H/M/L), probability (H/M/L), and mitigation
Critical (required when applicable)
Determine applicability from project context. If applicable but missing, ask using AskUserQuestion.
| Section | Required When |
|---|---|
| Security Considerations | Payments, auth, PII, external integrations |
| Monitoring & Observability | Production systems |
Security: auth/authz approach, encryption (at rest, in transit), PII handling and retention, compliance requirements (GDPR, PCI DSS), secrets management, webhook signature validation.
Monitoring: key metrics with alert thresholds, structured log format and what never to log (secrets, card numbers), alert severity and response actions.
Suggested (offer based on project size)
After mandatory and critical sections, offer these. Skip most for small/simple projects; include all relevant ones for large/complex projects.
| Section | When Valuable |
|---|---|
| Alternatives Considered | Multiple viable approaches existed |
| Performance Requirements | Latency/throughput/availability targets |
| Dependencies | External services, team dependencies, blockers |
| Migration Plan | Replacing existing systems |
| Open Questions | Unresolved decisions blocking implementation |
| Success Metrics | Business KPIs, adoption targets |
| Glossary | Domain-specific terminology |
| Approval & Sign-off | Requires stakeholder approval |
Process
Step 1: Check for Upstream Artifacts
Before gathering context, look for an existing PRD at .specs/[feature-slug]/PRODUCT-REQUIREMENTS.md. If the feature slug is not yet known, ask for the feature name first and derive the slug.
- PRD found: Read it. Use it as the source of truth for requirements, scope, and problem statement. Skip asking for information already covered by the PRD.
- PRD not found: Proceed to gather context directly in Step 2.
Step 2: Gather Context
Ask for:
- Project/feature name (if not already known from Step 1)
- Project type (new feature, integration, refactor/migration, etc.)
- Whether a clear problem statement exists or needs defining (skip if PRD was found)
Step 3: Collect Mandatory Information
Ensure you have enough to write all mandatory sections. Ask for anything missing (skip fields already answered by the PRD):
- Tech lead and team members
- Problem with impact (what, why, quantified consequences)
- In-scope and out-of-scope items (min 3 each)
- High-level solution approach
- At least 3 risks
Step 4: Determine Critical Sections
Based on project type, identify required critical sections:
- Payment/auth/PII projects: Security is mandatory
- Production systems: Monitoring is mandatory
Step 5: Offer Suggested Sections
Based on project size, offer relevant suggested sections. Ask: "Would you like to include any of these sections?"
Step 6: Generate and Validate
File location: .specs/[feature-slug]/TECHNICAL-DESIGN.md — derive the slug from the feature name (lowercase, hyphen-separated). Create the directory if it does not exist.
Generate using the template below. Validate against the checklist. Highlight any gaps in the output summary.
Template
# Technical Design — [Project/Feature Name]
| Field | Value |
| ------------ | ---------------------------- |
| Tech Lead | @Name |
| Team | Name1, Name2, Name3 |
| Epic/Ticket | [Link] |
| Status | Draft / In Review / Approved |
| Created | YYYY-MM-DD |
| Last Updated | YYYY-MM-DD |
## Context
2–4 paragraphs: current state, related system/feature, business domain, stakeholders.
## Problem Statement & Motivation
### Problems We're Solving
- **[Problem 1]**: [Pain point] — Impact: [Quantify]
- **[Problem 2]**: [Pain point] — Impact: [Quantify]
### Why Now?
- [Business, technical, or user driver]
### Cost of Inaction
- **Business**: [Revenue loss, competitive disadvantage]
- **Technical**: [Debt accumulation, system degradation]
- **Users**: [Poor experience, churn risk]
## Scope
### In Scope (V1)
- [Capability 1]
- [Capability 2]
- [Capability 3]
### Out of Scope (V1)
- [Item 1] (deferred to V2)
- [Item 2] (not needed for MVP)
- [Item 3] (future enhancement)
### Future Considerations (V2+)
- [Item dependent on V1 validation]
## Technical Solution
### Architecture Overview
[High-level description of the solution]
**Key Components**:
- [Component A]: [responsibility]
- [Component B]: [responsibility]
**Architecture Diagram**:
[Mermaid diagram showing component interactions]
### Data Flow
1. [Step 1]: [Source] → [Destination] ([protocol/method])
2. [Step 2]: [Source] → [Destination] ([protocol/method])
### APIs & Endpoints
| Endpoint | Method | Description | Request | Response |
|----------|--------|-------------|---------|----------|
| [path] | [verb] | [what it does] | [schema] | [schema/status] |
### Database Changes
**New Tables**: [TableName] — [description], fields with types, indexes with rationale
**Schema Modifications**: [Change with type, constraints, migration strategy]
## Key Decisions & Trade-offs
| Decision | Choice Made | Alternatives Rejected | Rationale |
|----------|-------------|-----------------------|-----------|
| [Topic] | [Chosen] | [Not chosen] | [Why] |
## Risks
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| [Description] | H/M/L | H/M/L | [Strategy] |Critical and suggested sections follow after Risks based on project type and size.
Validation Checklist
- Header has tech lead, team, and epic link
- Context has 2+ paragraphs with background and domain
- Problem statement has 2+ specific problems with quantified impact
- Scope has 3+ in-scope and 3+ out-of-scope items
- Technical solution has architecture diagram and API contracts
- Key decisions table is present with rationale
- Risks has 3+ entries with impact, probability, and mitigation
- Security section present (payment/auth/PII projects)
- Monitoring section present (production systems)
- No implementation details (code snippets, CLI commands, framework syntax)
Output Summary
After generating, provide:
Technical Design Created: "[Project Name]"
File: .specs/[feature-slug]/TECHNICAL-DESIGN.md
Sections Included:
- Mandatory (N/7): [list]
- Critical (N/N): [list]
- Suggested: [list]
Missing (if any):
- [Section]: [why it matters]
Suggested Next Steps:
- Share for team review
- Run /create-implementation-plan to plan execution
- [Other actionable items]