Technical Design Doc Creator
A skill for AI coding agents that helps create comprehensive Technical Design Documents (TDDs) following industry standards.
What It Does
This skill guides AI agents to create well-structured Technical Design Documents that include:
- Mandatory sections: Context, Problem Statement, Scope, Technical Solution, Risks, Implementation Plan
- Critical sections: Security (for payments/auth), Monitoring, Rollback Plan, Testing Strategy
- Optional sections: Success Metrics, Glossary, Alternatives Considered, Dependencies, Performance Requirements, and more
The skill automatically adapts to:
- Project size: Small (< 1 week), Medium (1-4 weeks), Large (> 1 month)
- Project type: Integration, Feature, Refactor, Infrastructure, Payment, Auth, Data migration
- User's language: Automatically generates TDD in Portuguese, English, or Spanish based on your request
How to Use
Basic Usage
Simply ask the AI agent to create a TDD:
English:
Create a TDD for Stripe payment integration
Portuguese:
Crie um TDD para integração com Stripe
Spanish:
Crea un TDD para integración con Stripe
Interactive Workflow
The skill will guide you through an interactive process:
- Initial Questions: Project name, size, type, and context clarity
- Mandatory Information: Problem statement, scope, technical approach
- Critical Sections: Security, monitoring, rollback (if applicable)
- Optional Sections: Success metrics, glossary, alternatives, etc.
Examples
Example 1: Payment Integration
Your Request:
Create a TDD for integrating Stripe payments into our subscription system
What Happens:
- Agent asks about project size and type
- Agent requests: problem statement, scope, technical approach
- Agent identifies this is a payment system → Security section becomes MANDATORY
- Agent asks for: security requirements, monitoring metrics, rollback plan
- Agent generates comprehensive TDD with all required sections
Result: A complete TDD with:
- Context and problem statement
- In-scope/out-of-scope features
- Architecture diagram
- API contracts
- Security considerations (PCI DSS compliance, encryption, PII handling)
- Testing strategy
- Monitoring & observability
- Rollback plan
- Implementation timeline
Example 2: Simple Feature
Your Request:
Write a design doc for adding user profile pictures
What Happens:
- Agent identifies this as a small feature
- Agent asks for basic information
- Agent generates streamlined TDD with essential sections only
Result: A focused TDD with:
- Context
- Problem statement
- Scope (in/out)
- Technical solution (file upload, storage, API endpoints)
- Risks
- Implementation plan
- Testing strategy
Example 3: Migration Project
Your Request:
Crie um TDD para migração do banco de dados PostgreSQL para MongoDB
What Happens:
- Agent detects Portuguese language → generates TDD in Portuguese
- Agent identifies this as a migration project
- Agent requests: migration strategy, data mapping, rollback plan
- Agent offers migration plan section
Result: A TDD in Portuguese with:
- Contexto (Context)
- Definição do Problema (Problem Statement)
- Escopo (Scope)
- Solução Técnica (Technical Solution)
- Plano de Migração (Migration Plan)
- Plano de Rollback (Rollback Plan)
- Estratégia de Testes (Testing Strategy)
What to Expect
The Agent Will Ask Questions
The skill is designed to gather complete information. Expect questions like:
For Problem Statement:
- What problem are we solving?
- Why is this important now?
- What happens if we don't solve it?
For Scope:
- What WILL be delivered in V1?
- What will NOT be included (out of scope)?
For Technical Approach:
- What are the main components?
- How does data flow through the system?
- What APIs will be created/modified?
For Payment/Auth Projects:
- How will you handle authentication?
- What encryption will be used?
- What PII is collected?
- Any compliance requirements (GDPR, PCI DSS)?
For Production Systems:
- How will you monitor this?
- What metrics matter?
- How will you rollback if something fails?
The Generated TDD
The TDD will include:
- Header & Metadata: Tech Lead, Team, Epic link, Status, Dates
- Context: Background, domain, stakeholders
- Problem Statement: Specific problems with quantified impact
- Scope: Clear in-scope and out-of-scope items
- Technical Solution: Architecture, data flow, APIs, database changes
- Risks: Risk matrix with impact, probability, and mitigation
- Implementation Plan: Phased breakdown with estimates
- Security (if applicable): Authentication, encryption, compliance
- Testing Strategy: Unit, integration, E2E test plans
- Monitoring & Observability: Metrics, alerts, dashboards
- Rollback Plan: Triggers and steps for reverting changes
- Optional sections: Success metrics, glossary, alternatives, dependencies, etc.
Tips for Best Results
1. Provide Context Early
Instead of:
Create a TDD for Stripe
Try:
Create a TDD for integrating Stripe payments. We need to support subscriptions,
handle webhooks, and comply with PCI DSS. This is for our SaaS product.
2. Be Specific About Scope
The agent will ask, but you can provide upfront:
Create a TDD for user authentication. In scope: email/password, JWT tokens,
password reset. Out of scope: OAuth, 2FA, social login (those are V2).
3. Mention Project Size
Create a TDD for the database migration project. This is a large project
(expected 2 months).
4. Specify Critical Requirements
For payment/auth systems, mention security requirements:
Create a TDD for Stripe integration. We need PCI DSS compliance, webhook
signature validation, and encrypted storage of payment method tokens.
5. Use Your Language
The skill automatically detects your language. Just write naturally:
- English: "Create a TDD for..."
- Portuguese: "Crie um TDD para..."
- Spanish: "Crea un TDD para..."
Language Support
The skill supports multiple languages:
| Language | Example Trigger |
|---|---|
| English | "Create a TDD for Stripe integration" |
| Portuguese | "Crie um TDD para integração com Stripe" |
| Spanish | "Crea un TDD para integración con Stripe" |
All section headers and content are automatically translated to match your language.
Integration with Other Skills
Confluence Publishing
After generating a TDD, the agent will offer to publish it to Confluence:
Would you like me to publish this TDD to Confluence?
- I can create a new page in your space
- Or update an existing page
Jira Integration
The TDD includes a metadata section for Epic/Ticket links. You can manually add these or ask the agent to help create Jira tickets.
What Makes This Skill Different
1. Industry Standards
Follows patterns from:
- Google Design Docs
- Amazon PR-FAQ (Working Backwards)
- RFC Pattern
- ADR (Architecture Decision Records)
- SRE Book (Monitoring, Rollback, SLOs)
- PCI DSS & OWASP (Security)
2. Architecture-Focused, Not Implementation
The TDD documents decisions and contracts, not code:
✅ Includes: API contracts, data schemas, architecture diagrams, strategies ❌ Avoids: CLI commands, code snippets, framework-specific implementation
3. Adaptive to Project Size
- Small projects: Essential sections only (7-9 sections)
- Medium projects: Mandatory + critical sections (11-13 sections)
- Large projects: All sections (up to 20 sections)
4. Mandatory Sections Enforcement
The agent will insist on completing mandatory sections before finalizing the TDD. You can't skip:
- Problem Statement
- Scope
- Technical Solution
- Risks
- Implementation Plan
5. Critical Sections for Specific Project Types
- Payment/Auth: Security section is MANDATORY
- Production: Monitoring and Rollback are MANDATORY
- Integration: Dependencies and Security are highly recommended
Common Use Cases
✅ Good Use Cases
- New feature development
- External API integration
- System migration or refactoring
- Infrastructure changes
- Payment/billing system design
- Authentication/authorization system
- Data processing pipelines
❌ Not Ideal For
- Bug fixes (too small)
- Code refactoring without architectural changes
- Documentation updates
- Simple configuration changes
Example Output Structure
# TDD - [Project Name]
## Metadata
- Tech Lead: @Name
- Team: Name1, Name2
- Status: Draft
- Created: 2026-02-04
## Context
[Background and domain description]
## Problem Statement & Motivation
[Specific problems with impact]
## Scope
### ✅ In Scope
[What will be delivered]
### ❌ Out of Scope
[What won't be included]
## Technical Solution
[Architecture, APIs, data flow, database changes]
## Risks
[Risk matrix with mitigation]
## Implementation Plan
[Phased breakdown with estimates]
## Security Considerations
[Authentication, encryption, compliance]
## Testing Strategy
[Unit, integration, E2E tests]
## Monitoring & Observability
[Metrics, alerts, dashboards]
## Rollback Plan
[Triggers and steps]
[Additional optional sections...]
Troubleshooting
The Agent Keeps Asking Questions
This is normal! The skill is designed to gather complete information. Answer the questions to get a comprehensive TDD.
I Want to Skip a Section
Mandatory sections cannot be skipped. For optional sections, you can say:
Skip the Alternatives Considered section for now
The TDD is Too Detailed
For small projects, specify the size:
This is a small project (< 1 week), keep it simple
The TDD is Missing Something
Tell the agent what's missing:
Add a section on performance requirements
Next Steps After Creating a TDD
- Review: Check all sections are complete
- Share: Get feedback from team members
- Approve: Get sign-off from stakeholders
- Implement: Use the TDD as a guide during development
- Update: Keep the TDD updated as the project evolves
Support
For issues or questions about this skill, refer to the main agent-skills repository.