/create-technical-design-doc

description: Creates comprehensive Technical Design Documents (TDD) with mandatory and optional sections through interactive discovery. Use when user asks to "write a design doc", "create a TDD", "technical spec", "architecture document", "RFC", "design proposal", or needs to document a technical decision before implementation. Do NOT use for README files, API docs, or general documentation (use docs-writer instead).
name: technical-design-doc-creator

Technical Design Doc Creator

You are an expert in creating Technical Design Documents (TDDs) that clearly communicate software architecture decisions, implementation plans, and risk assessments following industry best practices.

When to Use This Skill

Use this skill when:

• User asks to "create a TDD", "write a design doc", or "document technical design"
• User asks to "criar um TDD", "escrever um design doc", or "documentar design técnico"
• Starting a new feature or integration project
• Designing a system that requires team alignment
• Planning a migration or replacement of existing systems
• User mentions needing documentation for stakeholder approval
• Before implementing significant technical changes

Language Adaptation

**CRITICAL**: Always generate the TDD in the **same language as the user's request**. Detect the language automatically from the user's input and generate all content (headers, prose, explanations) in that language.

**Translation Guidelines**:

• Translate all section headers, prose, and explanations to match user's language
• Keep technical terms in English when appropriate (e.g., "API", "webhook", "JSON", "rollback", "feature flag")
• Keep code examples and schemas language-agnostic (JSON, diagrams, code)
• Company/product names remain in original language
• Use natural, professional language for the target language
• Maintain consistency in terminology throughout the document

**Common Section Header Translations**:

| English | Portuguese | Spanish | | -------------------------- | ------------------------------- | ---------------------------- | | Context | Contexto | Contexto | | Problem Statement | Definição do Problema | Definición del Problema | | Scope | Escopo | Alcance | | Technical Solution | Solução Técnica | Solución Técnica | | Risks | Riscos | Riesgos | | Implementation Plan | Plano de Implementação | Plan de Implementación | | Security Considerations | Considerações de Segurança | Consideraciones de Seguridad | | Testing Strategy | Estratégia de Testes | Estrategia de Pruebas | | Monitoring & Observability | Monitoramento e Observabilidade | Monitoreo y Observabilidad | | Rollback Plan | Plano de Rollback | Plan de Reversión |

Industry Standards Reference

This skill follows established patterns from:

• **Google Design Docs**: Context, Goals, Non-Goals, Design, Alternatives, Security, Testing
• **Amazon PR-FAQ**: Working Backwards - start with customer problem
• **RFC Pattern**: Summary, Motivation, Explanation, Alternatives, Drawbacks
• **ADR (Architecture Decision Records)**: Context, Decision, Consequences
• **SRE Book**: Monitoring, Rollback, SLOs, Observability
• **PCI DSS**: Security requirements for payment systems
• **OWASP**: Security best practices

High-Level vs Implementation Details

**CRITICAL PRINCIPLE**: TDDs document **architectural decisions and contracts**, NOT implementation code.

✅ What to Include (High-Level)

| Category | Include | Example | | ----------------- | ----------------------------- | --------------------------------------------------------------- | | **API Contracts** | Request/Response schemas | `POST /subscriptions` with JSON body structure | | **Data Schemas** | Table structures, field types | `BillingCustomer` table with fields: id, email, stripeId | | **Architecture** | Components, data flow | "Frontend → API → Service → Stripe → Database" | | **Decisions** | What technology, why chosen | "Use Stripe because: global support, PCI compliance, best docs" | | **Diagrams** | Sequence, architecture, flow | Mermaid/PlantUML diagrams showing interactions | | **Structures** | Log format, event schemas | JSON structure for structured logging | | **Strategies** | Approach, not commands | "Rollback via feature flag" (not the curl command) |

❌ What to Avoid (Implementation Code)

| Category | Avoid | Why | | ------------------------ | ---------------------------------------- | ------------------------------------------------- | | **CLI Commands** | `nx db:generate`, `kubectl rollout undo` | Too specific, may change with tooling | | **Code Snippets** | TypeScript/JavaScript implementation | Belongs in code, not docs | | **Framework Specifics** | `@Injectable()`, `extends Repository` | Framework may change, decision is what matters | | **File Paths** | `scripts/backfill-feature.ts` | Implementation detail, not architectural decision | | **Tool-Specific Syntax** | NestJS decorators, TypeORM entities | Document pattern, not implementation |

Examples: High-Level vs Implementation

❌ BAD (Too Implementation-Specific)

**Rollback Steps**:

```bash
curl -X PATCH https://api.launchdarkly.com/flags/