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:

1. Initial Questions: Project name, size, type, and context clarity
2. Mandatory Information: Problem statement, scope, technical approach
3. Critical Sections: Security, monitoring, rollback (if applicable)
4. 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:

1. Agent asks about project size and type
2. Agent requests: problem statement, scope, technical approach
3. Agent identifies this is a payment system → Security section becomes MANDATORY
4. Agent asks for: security requirements, monitoring metrics, rollback plan
5. 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:

1. Agent identifies this as a small feature
2. Agent asks for basic information
3. 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:

1. Agent detects Portuguese language → generates TDD in Portuguese
2. Agent identifies this as a migration project
3. Agent requests: migration strategy, data mapping, rollback plan
4. 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:

1. Header & Metadata: Tech Lead, Team, Epic link, Status, Dates
2. Context: Background, domain, stakeholders
3. Problem Statement: Specific problems with quantified impact
4. Scope: Clear in-scope and out-of-scope items
5. Technical Solution: Architecture, data flow, APIs, database changes
6. Risks: Risk matrix with impact, probability, and mitigation
7. Implementation Plan: Phased breakdown with estimates
8. Security (if applicable): Authentication, encryption, compliance
9. Testing Strategy: Unit, integration, E2E test plans
10. Monitoring & Observability: Metrics, alerts, dashboards
11. Rollback Plan: Triggers and steps for reverting changes
12. 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

1. Review: Check all sections are complete
2. Share: Get feedback from team members
3. Approve: Get sign-off from stakeholders
4. Implement: Use the TDD as a guide during development
5. Update: Keep the TDD updated as the project evolves

Support

For issues or questions about this skill, refer to the main agent-skills repository.