[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6FJ5Y7GSFGR0T609ZPW2ZYC":3,"skill-same:01M6FJ5Y7GSFGR0T609ZPW2ZYC":68},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":33,"publishedAt":41,"linkOnly":42,"markdownContent":43,"markdownBody":43,"frontMatter":44,"refName":45,"commitSha":46,"skillDirectory":47,"forksCount":48,"repositoryHtmlUrl":49,"repositoryHomepageUrl":50,"ownerHtmlUrl":51,"ownerBlogUrl":6,"ownerDescription":52,"updatedAt":53,"install":54,"resources":67},"01M6FJ5Y7GSFGR0T609ZPW2ZYC","create-technical-design-doc",null,"ComeOnOliver\u002Fskillshub","ComeOnOliver","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43215937?v=4","01M6E5JNFECJAAVFE0W7SMWWD2","Haoran Shu","01M6E5JNNDQS7AJZDYFQ8TPZCK",66,"MIT","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Ftech-leads-club\u002Fagent-skills\u002Fcreate-technical-design-doc\u002FSKILL.md",[17,22,25,28],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":26,"categoryName":27,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":29,"categoryName":30,"taxonomyType":31,"taxonomyTypeDesc":32},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[34,35,36,37,38,39,40],"design","create","doc","design doc","technical","technical design","create technical design doc","2026-11-10 10:12:30",false,"# Technical Design Doc Creator\n\nYou are an expert in creating Technical Design Documents (TDDs) that clearly communicate software architecture decisions, implementation plans, and risk assessments following industry best practices.\n\n## When to Use This Skill\n\nUse this skill when:\n\n- User asks to \"create a TDD\", \"write a design doc\", or \"document technical design\"\n- User asks to \"criar um TDD\", \"escrever um design doc\", or \"documentar design técnico\"\n- Starting a new feature or integration project\n- Designing a system that requires team alignment\n- Planning a migration or replacement of existing systems\n- User mentions needing documentation for stakeholder approval\n- Before implementing significant technical changes\n\n## Language Adaptation\n\n**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.\n\n**Translation Guidelines**:\n\n- Translate all section headers, prose, and explanations to match user's language\n- Keep technical terms in English when appropriate (e.g., \"API\", \"webhook\", \"JSON\", \"rollback\", \"feature flag\")\n- Keep code examples and schemas language-agnostic (JSON, diagrams, code)\n- Company\u002Fproduct names remain in original language\n- Use natural, professional language for the target language\n- Maintain consistency in terminology throughout the document\n\n**Common Section Header Translations**:\n\n| English                    | Portuguese                      | Spanish                      |\n| -------------------------- | ------------------------------- | ---------------------------- |\n| Context                    | Contexto                        | Contexto                     |\n| Problem Statement          | Definição do Problema           | Definición del Problema      |\n| Scope                      | Escopo                          | Alcance                      |\n| Technical Solution         | Solução Técnica                 | Solución Técnica             |\n| Risks                      | Riscos                          | Riesgos                      |\n| Implementation Plan        | Plano de Implementação          | Plan de Implementación       |\n| Security Considerations    | Considerações de Segurança      | Consideraciones de Seguridad |\n| Testing Strategy           | Estratégia de Testes            | Estrategia de Pruebas        |\n| Monitoring & Observability | Monitoramento e Observabilidade | Monitoreo y Observabilidad   |\n| Rollback Plan              | Plano de Rollback               | Plan de Reversión            |\n\n## Industry Standards Reference\n\nThis skill follows established patterns from:\n\n- **Google Design Docs**: Context, Goals, Non-Goals, Design, Alternatives, Security, Testing\n- **Amazon PR-FAQ**: Working Backwards - start with customer problem\n- **RFC Pattern**: Summary, Motivation, Explanation, Alternatives, Drawbacks\n- **ADR (Architecture Decision Records)**: Context, Decision, Consequences\n- **SRE Book**: Monitoring, Rollback, SLOs, Observability\n- **PCI DSS**: Security requirements for payment systems\n- **OWASP**: Security best practices\n\n## High-Level vs Implementation Details\n\n**CRITICAL PRINCIPLE**: TDDs document **architectural decisions and contracts**, NOT implementation code.\n\n### ✅ What to Include (High-Level)\n\n| Category          | Include                       | Example                                                         |\n| ----------------- | ----------------------------- | --------------------------------------------------------------- |\n| **API Contracts** | Request\u002FResponse schemas      | `POST \u002Fsubscriptions` with JSON body structure                  |\n| **Data Schemas**  | Table structures, field types | `BillingCustomer` table with fields: id, email, stripeId        |\n| **Architecture**  | Components, data flow         | \"Frontend → API → Service → Stripe → Database\"                  |\n| **Decisions**     | What technology, why chosen   | \"Use Stripe because: global support, PCI compliance, best docs\" |\n| **Diagrams**      | Sequence, architecture, flow  | Mermaid\u002FPlantUML diagrams showing interactions                  |\n| **Structures**    | Log format, event schemas     | JSON structure for structured logging                           |\n| **Strategies**    | Approach, not commands        | \"Rollback via feature flag\" (not the curl command)              |\n\n### ❌ What to Avoid (Implementation Code)\n\n| Category                 | Avoid                                    | Why                                               |\n| ------------------------ | ---------------------------------------- | ------------------------------------------------- |\n| **CLI Commands**         | `nx db:generate`, `kubectl rollout undo` | Too specific, may change with tooling             |\n| **Code Snippets**        | TypeScript\u002FJavaScript implementation     | Belongs in code, not docs                         |\n| **Framework Specifics**  | `@Injectable()`, `extends Repository`    | Framework may change, decision is what matters    |\n| **File Paths**           | `scripts\u002Fbackfill-feature.ts`            | Implementation detail, not architectural decision |\n| **Tool-Specific Syntax** | NestJS decorators, TypeORM entities      | Document pattern, not implementation              |\n\n### Examples: High-Level vs Implementation\n\n#### ❌ BAD (Too Implementation-Specific)\n\n````markdown\n**Rollback Steps**:\n\n```bash\ncurl -X PATCH https:\u002F\u002Fapi.launchdarkly.com\u002Fflags\u002FFEATURE_X \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -d '{\"enabled\": false}'\n\nnx db:rollback billing\n```\n````\n\n````\n\n#### ✅ GOOD (High-Level Decision)\n\n```markdown\n**Rollback Steps**:\n1. Disable feature flag via feature flag service dashboard\n2. Revert database schema using down migration\n3. Verify system returns to previous state\n4. Monitor error rates to confirm rollback success\n````\n\n#### ❌ BAD (Implementation Code)\n\n````markdown\n**Service Implementation**:\n\n```typescript\n@Injectable()\nexport class CustomerService {\n  @Transactional({ connectionName: 'billing' })\n  async create(data: CreateCustomerDto) {\n    const customer = new Customer()\n    customer.email = data.email\n    return this.repository.save(customer)\n  }\n}\n```\n````\n\n````\n\n#### ✅ GOOD (High-Level Structure)\n\n```markdown\n**Service Layer**:\n- `CustomerService`: Manages customer lifecycle\n  - `create()`: Creates customer, validates email uniqueness\n  - `getById()`: Retrieves customer by ID\n  - `updatePaymentMethod()`: Updates default payment method\n- All write operations use transactions to ensure data consistency\n- Services call external Stripe API and cache results locally\n````\n\n### Guideline: Ask \"Will This Change?\"\n\nBefore adding detail to TDD, ask:\n\n- **\"If we change frameworks, does this detail still apply?\"**\n  - YES → Include (it's an architectural decision)\n  - NO → Exclude (it's implementation detail)\n\n- **\"Can someone implement this differently and still meet the requirement?\"**\n  - YES → Focus on the requirement, not the implementation\n  - NO → You might be too specific\n\n**Goal**: TDD should survive implementation changes. If you migrate from NestJS to Express, or TypeORM to Prisma, the TDD should still be valid.\n\n## Document Structure\n\n### Mandatory Sections (Must Have)\n\nThese sections are **required**. If the user doesn't provide information, you **must ask** using AskQuestion tool:\n\n1. **Header & Metadata**\n2. **Context**\n3. **Problem Statement & Motivation**\n4. **Scope** (In Scope \u002F Out of Scope)\n5. **Technical Solution**\n6. **Risks**\n7. **Implementation Plan**\n\n### Critical Sections (Ask if Missing)\n\nThese are **highly recommended** especially for:\n\n- Payment integrations (Security is MANDATORY)\n- Production systems (Monitoring, Rollback are MANDATORY)\n- External integrations (Dependencies, Security)\n\n8. **Security Considerations** (MANDATORY for payments\u002Fauth\u002FPII)\n9. **Testing Strategy**\n10. **Monitoring & Observability**\n11. **Rollback Plan**\n\n### Suggested Sections (Offer to User)\n\nAsk user: \"Would you like to add these sections now or later?\"\n\n12. **Success Metrics**\n13. **Glossary & Domain Terms**\n14. **Alternatives Considered**\n15. **Dependencies**\n16. **Performance Requirements**\n17. **Migration Plan** (if applicable)\n18. **Open Questions**\n19. **Roadmap \u002F Timeline**\n20. **Approval & Sign-off**\n\n## Project Size Adaptation\n\nUse this heuristic to determine project complexity:\n\n### Small Project (\u003C 1 week)\n\n**Use sections**: 1, 2, 3, 4, 5, 6, 7, 9\n\n**Skip**: Alternatives, Migration Plan, Approval\n\n### Medium Project (1-4 weeks)\n\n**Use sections**: 1-11, 15, 18\n\n**Offer**: Success Metrics, Glossary, Alternatives, Performance\n\n### Large Project (> 1 month)\n\n**Use all sections** (1-20)\n\n**Critical**: All mandatory + critical sections must be detailed\n\n## Interactive Workflow\n\n### Step 1: Initial Gathering\n\nUse **AskQuestion** tool to collect basic information:\n\n```json\n{\n  \"title\": \"TDD Project Information\",\n  \"questions\": [\n    {\n      \"id\": \"project_name\",\n      \"prompt\": \"What is the name of the feature\u002Fintegration\u002Fproject?\",\n      \"options\": [] \u002F\u002F Free text\n    },\n    {\n      \"id\": \"project_size\",\n      \"prompt\": \"What is the expected project size?\",\n      \"options\": [\n        { \"id\": \"small\", \"label\": \"Small (\u003C 1 week)\" },\n        { \"id\": \"medium\", \"label\": \"Medium (1-4 weeks)\" },\n        { \"id\": \"large\", \"label\": \"Large (> 1 month)\" }\n      ]\n    },\n    {\n      \"id\": \"project_type\",\n      \"prompt\": \"What type of project is this?\",\n      \"allow_multiple\": true,\n      \"options\": [\n        { \"id\": \"integration\", \"label\": \"External integration (API, service)\" },\n        { \"id\": \"feature\", \"label\": \"New feature\" },\n        { \"id\": \"refactor\", \"label\": \"Refactoring\u002Fmigration\" },\n        { \"id\": \"infrastructure\", \"label\": \"Infrastructure\u002Fplatform\" },\n        { \"id\": \"payment\", \"label\": \"Payment\u002Fbilling system\" },\n        { \"id\": \"auth\", \"label\": \"Authentication\u002Fauthorization\" },\n        { \"id\": \"data\", \"label\": \"Data migration\u002Fprocessing\" }\n      ]\n    },\n    {\n      \"id\": \"has_context\",\n      \"prompt\": \"Do you have a clear problem statement and context?\",\n      \"options\": [\n        { \"id\": \"yes\", \"label\": \"Yes, I can provide it now\" },\n        { \"id\": \"partial\", \"label\": \"Partially, need help clarifying\" },\n        { \"id\": \"no\", \"label\": \"No, need help defining it\" }\n      ]\n    }\n  ]\n}\n```\n\n### Step 2: Validate Mandatory Information\n\nBased on answers, check if user can provide:\n\n**MANDATORY fields to ask if missing**:\n\n- Tech Lead \u002F Owner\n- Team members\n- Problem description (what\u002Fwhy\u002Fimpact)\n- What is in scope\n- What is out of scope\n- High-level solution approach\n- At least 3 risks\n- Implementation tasks breakdown\n\n**Ask using AskQuestion or natural conversation IN THE USER'S LANGUAGE**:\n\n**English Example**:\n\n```\nI need the following information to create the TDD:\n\n1. **Problem Statement**:\n   - What problem are we solving?\n   - Why is this important now?\n   - What happens if we don't solve it?\n\n2. **Scope**:\n   - What WILL be delivered in this project?\n   - What will NOT be included (out of scope)?\n\n3. **Technical Approach**:\n   - High-level description of the solution\n   - Main components involved\n   - Integration points\n\nCan you provide this information?\n```\n\n**Portuguese Example**:\n\n```\nPreciso das seguintes informações para criar o TDD:\n\n1. **Definição do Problema**:\n   - Que problema estamos resolvendo?\n   - Por que isso é importante agora?\n   - O que acontece se não resolvermos?\n\n2. **Escopo**:\n   - O que SERÁ entregue neste projeto?\n   - O que NÃO será incluído (fora do escopo)?\n\n3. **Abordagem Técnica**:\n   - Descrição de alto nível da solução\n   - Principais componentes envolvidos\n   - Pontos de integração\n\nVocê pode fornecer essas informações?\n```\n\n### Step 3: Check for Critical Sections\n\nBased on `project_type`, determine if critical sections are mandatory:\n\n| Project Type      | Critical Sections Required                 |\n| ----------------- | ------------------------------------------ |\n| `payment`, `auth` | **Security Considerations** (MANDATORY)    |\n| All production    | **Monitoring & Observability** (MANDATORY) |\n| All production    | **Rollback Plan** (MANDATORY)              |\n| `integration`     | **Dependencies**, **Security**             |\n| All               | **Testing Strategy** (highly recommended)  |\n\n**If critical sections are missing, ASK IN THE USER'S LANGUAGE**:\n\n**English**:\n\n```\nThis is a [payment\u002Fauth\u002Fproduction] system. These sections are CRITICAL:\n\n❗ **Security Considerations** - Required for compliance (PCI DSS, OWASP)\n❗ **Monitoring & Observability** - Required to detect issues in production\n❗ **Rollback Plan** - Required to revert if something fails\n\nCan you provide:\n1. Security requirements (auth, encryption, PII handling)?\n2. What metrics will you monitor?\n3. How will you rollback if something goes wrong?\n```\n\n**Portuguese**:\n\n```\nEste é um sistema de [pagamento\u002Fautenticação\u002Fprodução]. Estas seções são CRÍTICAS:\n\n❗ **Considerações de Segurança** - Obrigatório para compliance (PCI DSS, OWASP)\n❗ **Monitoramento e Observabilidade** - Obrigatório para detectar problemas em produção\n❗ **Plano de Rollback** - Obrigatório para reverter se algo falhar\n\nVocê pode fornecer:\n1. Requisitos de segurança (autenticação, encriptação, tratamento de PII)?\n2. Quais métricas você vai monitorar?\n3. Como você fará rollback se algo der errado?\n```\n\n### Step 4: Offer Suggested Sections\n\nAfter mandatory sections are covered, **offer optional sections IN THE USER'S LANGUAGE**:\n\n**English**:\n\n```\nI can also add these sections to make the TDD more complete:\n\n? **Success Metrics** - How will you measure success?\n? **Glossary** - Define domain-specific terms\n⚖️ **Alternatives Considered** - Why this approach over others?\n? **Dependencies** - External services\u002Fteams needed\n⚡ **Performance Requirements** - Latency, throughput, availability targets\n? **Open Questions** - Track pending decisions\n\nWould you like me to add any of these now? (You can add them later)\n```\n\n**Portuguese**:\n\n```\nTambém posso adicionar estas seções para tornar o TDD mais completo:\n\n? **Métricas de Sucesso** - Como você vai medir o sucesso?\n? **Glossário** - Definir termos específicos do domínio\n⚖️ **Alternativas Consideradas** - Por que esta abordagem ao invés de outras?\n? **Dependências** - Serviços\u002Ftimes externos necessários\n⚡ **Requisitos de Performance** - Latência, throughput, disponibilidade\n? **Questões em Aberto** - Rastrear decisões pendentes\n\nGostaria que eu adicionasse alguma dessas agora? (Você pode adicionar depois)\n```\n\n### Step 5: Generate Document\n\nGenerate the TDD in Markdown format following the templates below.\n\n### Step 6: Offer Confluence Integration\n\nIf user has Confluence Assistant skill available, **ask in their language**:\n\n**English**:\n\n```\nWould you like me to publish this TDD to Confluence?\n- I can create a new page in your space\n- Or update an existing page\n```\n\n**Portuguese**:\n\n```\nGostaria que eu publicasse este TDD no Confluence?\n- Posso criar uma nova página no seu espaço\n- Ou atualizar uma página existente\n```\n\n## Section Templates\n\n### 1. Header & Metadata (MANDATORY)\n\n```markdown\n# TDD - [Project\u002FFeature Name]\n\n| Field           | Value                        |\n| --------------- | ---------------------------- |\n| Tech Lead       | @Name                        |\n| Product Manager | @Name (if applicable)        |\n| Team            | Name1, Name2, Name3          |\n| Epic\u002FTicket     | [Link to Jira\u002FLinear]        |\n| Figma\u002FDesign    | [Link if applicable]         |\n| Status          | Draft \u002F In Review \u002F Approved |\n| Created         | YYYY-MM-DD                   |\n| Last Updated    | YYYY-MM-DD                   |\n```\n\n**If user doesn't provide**: Ask for Tech Lead, Team members, and Epic link.\n\n---\n\n### 2. Context (MANDATORY)\n\n```markdown\n## Context\n\n[2-4 paragraph description of the project]\n\n**Background**:\nWhat is the current state? What system\u002Ffeature does this relate to?\n\n**Domain**:\nWhat business domain is this part of? (e.g., billing, authentication, content delivery)\n\n**Stakeholders**:\nWho cares about this project? (users, business, compliance, etc.)\n```\n\n**If unclear**: Ask \"Can you describe the current situation and what business domain this relates to?\"\n\n---\n\n### 3. Problem Statement & Motivation (MANDATORY)\n\n```markdown\n## Problem Statement & Motivation\n\n### Problems We're Solving\n\n- **Problem 1**: [Specific pain point with impact]\n  - Impact: [quantify if possible - time wasted, cost, user friction]\n- **Problem 2**: [Another pain point]\n  - Impact: [quantify if possible]\n\n### Why Now?\n\n- [Business driver - market expansion, competitor pressure, regulatory requirement]\n- [Technical driver - technical debt, scalability limits]\n- [User driver - customer feedback, usage patterns]\n\n### Impact of NOT Solving\n\n- **Business**: [revenue loss, competitive disadvantage]\n- **Technical**: [technical debt accumulation, system degradation]\n- **Users**: [poor experience, churn risk]\n```\n\n**If user says \"to integrate with X\"**: Ask \"What specific problems will this integration solve? Why is it important now? What happens if we don't do it?\"\n\n---\n\n### 4. Scope (MANDATORY)\n\n```markdown\n## Scope\n\n### ✅ In Scope (V1 - MVP)\n\nExplicit list of what WILL be delivered:\n\n- Feature\u002Fcapability 1\n- Feature\u002Fcapability 2\n- Feature\u002Fcapability 3\n- Integration point A\n- Data migration for X\n\n### ❌ Out of Scope (V1)\n\nExplicit list of what will NOT be included in this phase:\n\n- Feature X (deferred to V2)\n- Integration Y (not needed for MVP)\n- Advanced analytics (future enhancement)\n- Multi-region support (V2)\n\n### ? Future Considerations (V2+)\n\nWhat might come later:\n\n- Feature A (user demand dependent)\n- Feature B (after V1 validation)\n```\n\n**If user doesn't define**: Ask \"What are the must-haves for V1? What can wait for later versions?\"\n\n---\n\n### 5. Technical Solution (MANDATORY)\n\n````markdown\n## Technical Solution\n\n### Architecture Overview\n\n[High-level description of the solution]\n\n**Key Components**:\n\n- Component A: [responsibility]\n- Component B: [responsibility]\n- Component C: [responsibility]\n\n**Architecture Diagram**:\n\n[Include Mermaid diagram, PlantUML, or link to diagram]\n\n```mermaid\ngraph LR\n    A[Frontend] -->|HTTP| B[API Gateway]\n    B -->|GraphQL| C[Backend Service]\n    C -->|REST| D[External API]\n    C -->|Write| E[(Database)]\n```\n````\n\n### Data Flow\n\n1. **Step 1**: User action → Frontend\n2. **Step 2**: Frontend → API Gateway (POST \u002Fresource)\n3. **Step 3**: API Gateway → Service Layer\n4. **Step 4**: Service → External API (if applicable)\n5. **Step 5**: Service → Database (persist)\n6. **Step 6**: Response → Frontend\n\n### APIs & Endpoints\n\n| Endpoint               | Method | Description      | Request     | Response         |\n| ---------------------- | ------ | ---------------- | ----------- | ---------------- |\n| `\u002Fapi\u002Fv1\u002Fresource`     | POST   | Creates resource | `CreateDto` | `ResourceDto`    |\n| `\u002Fapi\u002Fv1\u002Fresource\u002F:id` | GET    | Get by ID        | -           | `ResourceDto`    |\n| `\u002Fapi\u002Fv1\u002Fresource\u002F:id` | DELETE | Delete resource  | -           | `204 No Content` |\n\n**Example Request\u002FResponse**:\n\n```json\n\u002F\u002F POST \u002Fapi\u002Fv1\u002Fresource\n{\n  \"name\": \"Example\",\n  \"type\": \"standard\"\n}\n\n\u002F\u002F Response 201 Created\n{\n  \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"name\": \"Example\",\n  \"type\": \"standard\",\n  \"status\": \"active\",\n  \"createdAt\": \"2026-02-04T10:00:00Z\"\n}\n```\n\n### Database Changes\n\n**New Tables**:\n\n- `{ModuleName}{EntityName}` - [description]\n  - Primary fields: id, userId, name, status\n  - Timestamps: createdAt, updatedAt\n  - Indexes: userId, status (for query performance)\n\n**Schema Changes** (if modifying existing):\n\n- Add column `newField` to `ExistingTable`\n  - Type: [varchar\u002Finteger\u002Fjsonb\u002Fetc.]\n  - Constraints: [nullable\u002Funique\u002Fforeign key]\n\n**Migration Strategy**:\n\n- Generate migration from schema changes\n- Test migration on staging environment first\n- Run during low-traffic window\n- Have rollback migration ready\n\n**Data Backfill** (if needed):\n\n- Affected records: Estimate quantity\n- Processing time: Estimate duration for data migration\n- Validation: How to verify data integrity after backfill\n\n````\n\n**If user provides vague description**: Ask \"What are the main components? How does data flow through the system? What APIs will be created\u002Fmodified?\"\n\n---\n\n### 6. Risks (MANDATORY)\n\n```markdown\n## Risks\n\n| Risk | Impact | Probability | Mitigation |\n|------|--------|-------------|------------|\n| External API downtime | High | Medium | Implement circuit breaker, cache responses, fallback to degraded mode |\n| Data migration failure | High | Low | Test on staging copy, run dry-run first, have rollback script ready |\n| Performance degradation | Medium | Medium | Load test before deployment, implement caching, monitor latency |\n| Security vulnerability | High | Low | Security review, penetration testing, follow OWASP guidelines |\n| Scope creep | Medium | High | Strict scope definition, change request process, regular stakeholder alignment |\n\n**Risk Scoring**:\n- **Impact**: High (system down, data loss) \u002F Medium (degraded UX) \u002F Low (minor inconvenience)\n- **Probability**: High (>50%) \u002F Medium (20-50%) \u002F Low (\u003C20%)\n````\n\n**If user provides \u003C 3 risks**: Ask \"What could go wrong? Consider: external dependencies, data integrity, performance, security, scope changes.\"\n\n---\n\n### 7. Implementation Plan (MANDATORY)\n\n```markdown\n## Implementation Plan\n\n| Phase                 | Task              | Description                            | Owner   | Status | Estimate |\n| --------------------- | ----------------- | -------------------------------------- | ------- | ------ | -------- |\n| **Phase 1 - Setup**   | Setup credentials | Obtain API keys, configure environment | @Dev1   | TODO   | 1d       |\n|                       | Database setup    | Create schema, configure datasource    | @Dev1   | TODO   | 1d       |\n| **Phase 2 - Core**    | Entities & repos  | Create TypeORM entities, repositories  | @Dev2   | TODO   | 3d       |\n|                       | Services          | Implement business logic services      | @Dev2   | TODO   | 4d       |\n| **Phase 3 - APIs**    | REST endpoints    | Create controllers, DTOs               | @Dev3   | TODO   | 3d       |\n|                       | Integration       | Integrate with external API            | @Dev1   | TODO   | 3d       |\n| **Phase 4 - Testing** | Unit tests        | Test services and repositories         | @Team   | TODO   | 2d       |\n|                       | E2E tests         | Test full flow                         | @Team   | TODO   | 3d       |\n| **Phase 5 - Deploy**  | Staging deploy    | Deploy to staging, smoke test          | @DevOps | TODO   | 1d       |\n|                       | Production deploy | Phased rollout to production           | @DevOps | TODO   | 1d       |\n\n**Total Estimate**: ~20 days (4 weeks)\n\n**Dependencies**:\n\n- Must complete Phase N before Phase N+1\n- External API access required before Phase 3\n- Security review required before Phase 5\n```\n\n**If user provides vague plan**: Ask \"Can you break this down into phases with specific tasks? Who will work on each part? What's the estimated timeline?\"\n\n---\n\n### 8. Security Considerations (CRITICAL for payments\u002Fauth\u002FPII)\n\n```markdown\n## Security Considerations\n\n### Authentication & Authorization\n\n- **Authentication**: How users prove identity\n  - Example: JWT tokens, OAuth 2.0, session-based\n- **Authorization**: What authenticated users can access\n  - Example: Role-based (RBAC), Attribute-based (ABAC)\n  - Ensure users can only access their own resources\n\n### Data Protection\n\n**Encryption**:\n\n- **At Rest**: Database encryption enabled (AES-256)\n- **In Transit**: TLS 1.3 for all API communication\n- **Secrets**: Store API keys in environment variables \u002F secret manager (AWS Secrets Manager, HashiCorp Vault)\n\n**PII Handling**:\n\n- What PII is collected: [email, name, payment info]\n- Legal basis: [consent, contract, legitimate interest]\n- Retention: [how long data is kept]\n- Deletion: [GDPR right to be forgotten implementation]\n\n### Compliance Requirements\n\n| Regulation  | Requirement                        | Implementation                                    |\n| ----------- | ---------------------------------- | ------------------------------------------------- |\n| **GDPR**    | Data protection, right to deletion | Implement data export\u002Fdeletion endpoints          |\n| **PCI DSS** | No storage of card data            | Use Stripe tokenization, never store CVV\u002Ffull PAN |\n| **LGPD**    | Brazil data protection             | Same as GDPR compliance                           |\n\n### Security Best Practices\n\n- ✅ Input validation on all endpoints\n- ✅ SQL injection prevention (parameterized queries)\n- ✅ XSS prevention (sanitize user input, CSP headers)\n- ✅ CSRF protection (tokens for state-changing operations)\n- ✅ Rate limiting (e.g., 10 req\u002Fmin per user, 100 req\u002Fmin per IP)\n- ✅ Audit logging (log all sensitive operations)\n\n### Secrets Management\n\n**API Keys**:\n\n- Storage: Environment variables or secret management service\n- Rotation: Define rotation policy (e.g., every 90 days)\n- Access: Backend services only, never exposed to frontend\n- Examples: Stripe keys, database credentials, API tokens\n\n**Webhook Signatures**:\n\n- Validate webhook signatures from external services\n- Reject requests without valid signature headers\n- Log invalid signature attempts for security monitoring\n```\n\n**If missing and project involves payments\u002Fauth**: Ask \"This is a [payment\u002Fauth] system. I need security details: How will you handle authentication? What encryption will be used? What PII is collected? Any compliance requirements (GDPR, PCI DSS)?\"\n\n---\n\n### 9. Testing Strategy (CRITICAL)\n\n```markdown\n## Testing Strategy\n\n| Test Type             | Scope                    | Coverage Target          | Approach             |\n| --------------------- | ------------------------ | ------------------------ | -------------------- |\n| **Unit Tests**        | Services, repositories   | > 80%                    | Jest with mocks      |\n| **Integration Tests** | API endpoints + database | Critical paths           | Supertest + test DB  |\n| **E2E Tests**         | Full user flows          | Happy path + error cases | Playwright           |\n| **Contract Tests**    | External API integration | API contract validation  | Pact or manual mocks |\n| **Load Tests**        | Performance under load   | Baseline performance     | k6 or Artillery      |\n\n### Test Scenarios\n\n**Unit Tests**:\n\n- ✅ Service business logic (create, update, delete)\n- ✅ Repository query methods\n- ✅ Error handling (throw correct exceptions)\n- ✅ Edge cases (null inputs, invalid data)\n\n**Integration Tests**:\n\n- ✅ POST `\u002Fapi\u002Fv1\u002Fresource` → creates in DB\n- ✅ GET `\u002Fapi\u002Fv1\u002Fresource\u002F:id` → returns correct data\n- ✅ DELETE `\u002Fapi\u002Fv1\u002Fresource\u002F:id` → removes from DB\n- ✅ Invalid input → returns 400 Bad Request\n- ✅ Unauthorized access → returns 401\u002F403\n\n**E2E Tests**:\n\n- ✅ User creates resource → success flow\n- ✅ User tries to access another user's resource → denied\n- ✅ External API fails → graceful degradation\n- ✅ Database connection lost → proper error handling\n\n**Load Tests**:\n\n- Target: 100 req\u002Fs sustained, 500 req\u002Fs peak\n- Monitor: Latency (p50, p95, p99), error rate, throughput\n- Pass criteria: p95 \u003C 500ms, error rate \u003C 1%\n\n### Test Data Management\n\n- Use factories for test data (e.g., `@faker-js\u002Ffaker`)\n- Seed test database with realistic data\n- Clean up test data after each test\n- Use separate test database (never use production)\n```\n\n**If missing**: Ask \"How will you test this? What test types are needed (unit, integration, e2e)? What are critical test scenarios?\"\n\n---\n\n### 10. Monitoring & Observability (CRITICAL for production)\n\n````markdown\n## Monitoring & Observability\n\n### Metrics to Track\n\n| Metric                    | Type       | Alert Threshold   | Dashboard          |\n| ------------------------- | ---------- | ----------------- | ------------------ |\n| `api.latency`             | Latency    | p95 > 1s for 5min | DataDog \u002F Grafana  |\n| `api.error_rate`          | Error rate | > 1% for 5min     | DataDog \u002F Grafana  |\n| `external_api.latency`    | Latency    | p95 > 2s for 5min | DataDog            |\n| `external_api.errors`     | Counter    | > 5 in 1min       | PagerDuty          |\n| `database.query_time`     | Duration   | p95 > 100ms       | DataDog            |\n| `webhook.processing_time` | Duration   | > 5s              | Internal Dashboard |\n\n### Structured Logging\n\n**Log Format** (JSON):\n\n```json\n{\n  \"level\": \"info\",\n  \"timestamp\": \"2026-02-04T10:00:00Z\",\n  \"message\": \"Resource created\",\n  \"context\": {\n    \"userId\": \"user-123\",\n    \"resourceId\": \"res-456\",\n    \"action\": \"create\",\n    \"duration_ms\": 45\n  }\n}\n```\n````\n\n**What to Log**:\n\n- ✅ All API requests (method, path, status, duration)\n- ✅ External API calls (endpoint, status, duration)\n- ✅ Database queries (slow queries > 100ms)\n- ✅ Errors and exceptions (stack trace, context)\n- ✅ Business events (resource created, payment processed)\n\n**What NOT to Log**:\n\n- ❌ Passwords, API keys, secrets\n- ❌ Full credit card numbers\n- ❌ Sensitive PII (redact or hash)\n\n### Alerts\n\n| Alert                              | Severity      | Channel            | On-Call Action                              |\n| ---------------------------------- | ------------- | ------------------ | ------------------------------------------- |\n| Error rate > 5%                    | P1 (Critical) | PagerDuty          | Immediate investigation, rollback if needed |\n| External API down                  | P1 (Critical) | PagerDuty          | Enable fallback mode, notify stakeholders   |\n| Latency > 2s (p95)                 | P2 (High)     | Slack #engineering | Investigate performance degradation         |\n| Webhook failures > 20              | P2 (High)     | Slack #engineering | Check webhook endpoint, Stripe status       |\n| Database connection pool exhausted | P1 (Critical) | PagerDuty          | Scale up connections or investigate leak    |\n\n### Dashboards\n\n**Operational Dashboard**:\n\n- Request rate (per endpoint)\n- Error rate (overall and per endpoint)\n- Latency (p50, p95, p99)\n- External API health\n- Database performance\n\n**Business Dashboard**:\n\n- Resources created (count per day)\n- Active users\n- Conversion metrics (if applicable)\n\n````\n\n**If missing for production system**: Ask \"How will you monitor this in production? What metrics matter? What alerts do you need?\"\n\n---\n\n### 11. Rollback Plan (CRITICAL for production)\n\n```markdown\n## Rollback Plan\n\n### Deployment Strategy\n\n- **Feature Flag**: `FEATURE_X_ENABLED` (LaunchDarkly \u002F custom)\n- **Phased Rollout**:\n  - Phase 1: 5% of traffic (1 day)\n  - Phase 2: 25% of traffic (1 day)\n  - Phase 3: 50% of traffic (1 day)\n  - Phase 4: 100% of traffic\n\n- **Canary Deployment**: Deploy to 1 instance first, monitor for 1h before full rollout\n\n### Rollback Triggers\n\n| Trigger | Action |\n|---------|--------|\n| Error rate > 5% for 5 minutes | **Immediate rollback** - disable feature flag |\n| Latency > 3s (p95) for 10 minutes | **Investigate** - rollback if no quick fix |\n| External API integration failing > 50% | **Rollback** - revert to previous version |\n| Database migration fails | **STOP** - do not proceed, investigate |\n| Customer reports of data loss | **Immediate rollback** + incident response |\n\n### Rollback Steps\n\n**1. Immediate Rollback (\u003C 5 minutes)**:\n- **Feature Flag**: Disable via feature flag dashboard (instant)\n- **Deployment**: Revert to previous version via deployment tool (2-3 minutes)\n\n**2. Database Rollback** (if schema changed):\n- Run down migration using migration tool\n- Verify schema integrity\n- Confirm data consistency\n\n**3. Communication**:\n\n- Notify #engineering Slack channel\n- Update status page (if customer-facing)\n- Create incident ticket\n- Schedule post-mortem within 24h\n\n### Post-Rollback\n\n- **Root Cause Analysis**: Within 24 hours\n- **Fix**: Implement fix in development environment\n- **Re-test**: Full test suite + additional tests for root cause\n- **Re-deploy**: Following same phased rollout strategy\n\n### Database Rollback Considerations\n\n- **Migrations**: Always create reversible migrations (down migration)\n- **Data Backfill**: If data was modified, have script to restore previous state\n- **Backup**: Take database snapshot before running migrations\n- **Testing**: Test rollback procedure on staging before production\n\n````\n\n**If missing for production**: Ask \"What happens if the deploy goes wrong? How will you rollback? What are the triggers for rollback?\"\n\n---\n\n### 12. Success Metrics (SUGGESTED)\n\n```markdown\n## Success Metrics\n\n| Metric                  | Baseline      | Target  | Measurement        |\n| ----------------------- | ------------- | ------- | ------------------ |\n| API latency (p95)       | N\u002FA (new API) | \u003C 200ms | DataDog APM        |\n| Error rate              | N\u002FA           | \u003C 0.1%  | Sentry \u002F logs      |\n| Conversion rate         | N\u002FA           | > 70%   | Analytics          |\n| User satisfaction       | N\u002FA           | NPS > 8 | User survey        |\n| Time to complete action | N\u002FA           | \u003C 30s   | Frontend analytics |\n\n**Business Metrics**:\n\n- Increase in [metric] by [X%]\n- Reduction in [cost\u002Ftime] by [Y%]\n- User adoption: [Z%] of users using new feature within 30 days\n\n**Technical Metrics**:\n\n- Zero production incidents in first 30 days\n- Test coverage > 80%\n- Documentation completeness: 100% of public APIs documented\n```\n\n---\n\n### 13. Glossary & Domain Terms (SUGGESTED)\n\n```markdown\n## Glossary\n\n| Term                | Description                                                           |\n| ------------------- | --------------------------------------------------------------------- |\n| **Customer**        | A user who has an active subscription or has made a purchase          |\n| **Subscription**    | Recurring payment arrangement with defined interval (monthly, annual) |\n| **Trial**           | Free period for users to test service before payment required         |\n| **Webhook**         | HTTP callback from external service to notify of events               |\n| **Idempotency**     | Operation can be applied multiple times with same result              |\n| **Circuit Breaker** | Pattern to prevent cascading failures when external service is down   |\n\n**Acronyms**:\n\n- **API**: Application Programming Interface\n- **SLA**: Service Level Agreement\n- **PII**: Personally Identifiable Information\n- **GDPR**: General Data Protection Regulation\n- **PCI DSS**: Payment Card Industry Data Security Standard\n```\n\n---\n\n### 14. Alternatives Considered (SUGGESTED)\n\n```markdown\n## Alternatives Considered\n\n| Option                | Pros                                                     | Cons                                                                        | Why Not Chosen                                    |\n| --------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------- |\n| **Option A** (Chosen) | + Best documentation\u003Cbr>+ Global support\u003Cbr>+ Mature SDK | - Cost: 2.9% + $0.30\u003Cbr>- Vendor lock-in                                    | ✅ **Chosen** - Best balance of features and cost |\n| Option B              | + Lower fees (2.5%)\u003Cbr>+ Brand recognition               | - Poor developer experience\u003Cbr>- Limited international support              | Developer experience inferior, harder to maintain |\n| Option C              | + Full control\u003Cbr>+ No transaction fees                  | - High maintenance cost\u003Cbr>- Compliance burden (PCI DSS)\u003Cbr>- Security risk | Too risky and expensive to maintain in-house      |\n| Option D              | + Cheapest option                                        | - No support\u003Cbr>- Limited features\u003Cbr>- Unknown reliability                 | Too risky for production payment processing       |\n\n**Decision Criteria**:\n\n1. Developer experience and documentation quality (weight: 40%)\n2. Total cost of ownership (weight: 30%)\n3. International support and compliance (weight: 20%)\n4. Reliability and uptime (weight: 10%)\n\n**Why Option A Won**:\n\n- Scored highest on developer experience (critical for fast iteration)\n- Industry-standard for startups (easier to hire developers with experience)\n- Built-in compliance (PCI DSS, SCA, 3D Secure) reduces risk\n```\n\n---\n\n### 15. Dependencies (SUGGESTED)\n\n```markdown\n## Dependencies\n\n| Dependency            | Type           | Owner       | Status           | Risk                |\n| --------------------- | -------------- | ----------- | ---------------- | ------------------- |\n| Stripe API            | External       | Stripe Inc. | Production-ready | Low (99.99% uptime) |\n| Identity Module       | Internal       | Team Auth   | Production-ready | Low                 |\n| Database (PostgreSQL) | Infrastructure | DevOps      | Ready            | Low                 |\n| Redis (caching)       | Infrastructure | DevOps      | Needs setup      | Medium              |\n| Feature flag service  | Internal       | Platform    | Ready            | Low                 |\n\n**Approval Requirements**:\n\n- [ ] Security team review (for payment\u002Fauth projects)\n- [ ] Compliance sign-off (for PII\u002Fpayment data)\n- [ ] Ops team ready for monitoring setup\n- [ ] Product sign-off on scope\n\n**Blockers**:\n\n- Waiting for Stripe production keys (ETA: 2026-02-10)\n- Need Redis setup in staging (ETA: 2026-02-08)\n```\n\n---\n\n### 16. Performance Requirements (SUGGESTED)\n\n```markdown\n## Performance Requirements\n\n| Metric              | Requirement                   | Measurement Method |\n| ------------------- | ----------------------------- | ------------------ |\n| API Latency (p50)   | \u003C 100ms                       | DataDog APM        |\n| API Latency (p95)   | \u003C 500ms                       | DataDog APM        |\n| API Latency (p99)   | \u003C 1s                          | DataDog APM        |\n| Throughput          | 1000 req\u002Fs sustained          | Load testing (k6)  |\n| Availability        | 99.9% (\u003C 8.76h downtime\u002Fyear) | Uptime monitoring  |\n| Database query time | \u003C 50ms (p95)                  | Slow query log     |\n\n**Load Testing Plan**:\n\n- Baseline: 100 req\u002Fs for 10 minutes\n- Peak: 500 req\u002Fs for 5 minutes\n- Spike: 1000 req\u002Fs for 1 minute\n\n**Scalability**:\n\n- Horizontal scaling: Add more instances (Kubernetes autoscaling)\n- Database: Read replicas if needed (after 10k req\u002Fs)\n- Caching: Redis for frequently accessed data (> 100 req\u002Fs per resource)\n```\n\n---\n\n### 17. Migration Plan (SUGGESTED - if applicable)\n\n```markdown\n## Migration Plan\n\n### Migration Strategy\n\n**Type**: [Blue-Green \u002F Rolling \u002F Big Bang \u002F Phased]\n\n**Phases**:\n\n| Phase             | Description                            | Users Affected | Duration | Rollback            |\n| ----------------- | -------------------------------------- | -------------- | -------- | ------------------- |\n| 1. Preparation    | Set up new system, run in parallel     | 0%             | 1 week   | N\u002FA                 |\n| 2. Shadow Mode    | New system processes but doesn't serve | 0%             | 1 week   | Instant             |\n| 3. Pilot          | 5% of users on new system              | 5%             | 1 week   | \u003C 5min              |\n| 4. Ramp Up        | 50% of users on new system             | 50%            | 1 week   | \u003C 5min              |\n| 5. Full Migration | 100% of users on new system            | 100%           | 1 day    | \u003C 5min              |\n| 6. Decommission   | Turn off old system                    | 0%             | 1 week   | Restore from backup |\n\n### Data Migration\n\n**Source**: Old system database\n**Destination**: New system database\n**Volume**: [X million records]\n**Method**: [ETL script \u002F database replication \u002F API sync]\n\n**Steps**:\n\n1. Export data from old system (script: `scripts\u002Fexport-old-data.ts`)\n2. Transform data to new schema (script: `scripts\u002Ftransform-data.ts`)\n3. Validate data integrity (checksums, row counts)\n4. Load into new system (script: `scripts\u002Fload-new-data.ts`)\n5. Verify: Run parallel reads, compare results\n\n**Timeline**:\n\n- Dry run on staging: 2026-02-10\n- Production migration window: 2026-02-15 02:00-06:00 UTC (low traffic)\n\n### Backward Compatibility\n\n- Old API endpoints will remain active for 90 days\n- Deprecation warnings added to responses\n- Client libraries updated with migration guide\n```\n\n---\n\n### 18. Open Questions (SUGGESTED)\n\n```markdown\n## Open Questions\n\n| #   | Question                                               | Context                                        | Owner     | Status           | Decision Date |\n| --- | ------------------------------------------------------ | ---------------------------------------------- | --------- | ---------------- | ------------- |\n| 1   | How to handle trial expiration without payment method? | User loses access immediately or grace period? | @Product  | ? In Discussion | TBD           |\n| 2   | Allow multiple trials for same email?                  | Prevent abuse vs. legitimate use cases         | @TechLead | ? Open          | TBD           |\n| 3   | SLA for webhook processing?                            | Stripe retries for 72h, what's our target?     | @Backend  | ? Open          | TBD           |\n| 4   | Support for promo codes in V1?                         | Marketing requested, is it in scope?           | @Product  | ✅ Resolved: V2  | 2026-02-01    |\n| 5   | Fallback if Identity Module fails?                     | Can we create subscription without user data?  | @TechLead | ? Open          | TBD           |\n\n**Status Legend**:\n\n- ? Open - needs decision\n- ? In Discussion - actively being discussed\n- ✅ Resolved - decision made\n```\n\n---\n\n### 19. Roadmap \u002F Timeline (SUGGESTED)\n\n```markdown\n## Roadmap \u002F Timeline\n\n| Phase                    | Deliverables                                                                      | Duration | Target Date | Status         |\n| ------------------------ | --------------------------------------------------------------------------------- | -------- | ----------- | -------------- |\n| **Phase 0: Setup**       | - Stripe credentials\u003Cbr>- Staging environment\u003Cbr>- SDK installed                  | 2 days   | 2026-02-05  | ✅ Complete    |\n| **Phase 1: Persistence** | - Entities created\u003Cbr>- Repositories implemented\u003Cbr>- Migrations generated        | 3 days   | 2026-02-08  | ? In Progress |\n| **Phase 2: Services**    | - CustomerService\u003Cbr>- SubscriptionService\u003Cbr>- Identity integration              | 5 days   | 2026-02-15  | ⏳ Pending     |\n| **Phase 3: APIs**        | - POST \u002Fsubscriptions\u003Cbr>- DELETE \u002Fsubscriptions\u002F:id\u003Cbr>- GET \u002Fsubscriptions      | 3 days   | 2026-02-18  | ⏳ Pending     |\n| **Phase 4: Webhooks**    | - Webhook endpoint\u003Cbr>- Signature validation\u003Cbr>- Event handlers                  | 4 days   | 2026-02-22  | ⏳ Pending     |\n| **Phase 5: Testing**     | - Unit tests (80% coverage)\u003Cbr>- Integration tests\u003Cbr>- E2E tests                 | 5 days   | 2026-02-27  | ⏳ Pending     |\n| **Phase 6: Deploy**      | - Documentation\u003Cbr>- Monitoring setup\u003Cbr>- Staging deploy\u003Cbr>- Production rollout | 3 days   | 2026-03-02  | ⏳ Pending     |\n\n**Total Duration**: ~25 days (5 weeks)\n\n**Milestones**:\n\n- ? M1: MVP ready for staging (2026-02-22)\n- ? M2: Production deployment (2026-03-02)\n- ? M3: 100% rollout complete (2026-03-09)\n\n**Critical Path**:\nPhase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6\n```\n\n---\n\n### 20. Approval & Sign-off (SUGGESTED)\n\n```markdown\n## Approval & Sign-off\n\n| Role                     | Name  | Status         | Date       | Comments                          |\n| ------------------------ | ----- | -------------- | ---------- | --------------------------------- |\n| Tech Lead                | @Name | ✅ Approved    | 2026-02-04 | LGTM, proceed with implementation |\n| Staff\u002FPrincipal Engineer | @Name | ⏳ Pending     | -          | Requested security review first   |\n| Product Manager          | @Name | ✅ Approved    | 2026-02-03 | Scope aligned with roadmap        |\n| Engineering Manager      | @Name | ⏳ Pending     | -          | -                                 |\n| Security Team            | @Name | ? Not Started | -          | Required for payment integration  |\n| Compliance\u002FLegal         | @Name | N\u002FA            | -          | Not required for this project     |\n\n**Approval Criteria**:\n\n- ✅ All mandatory sections complete\n- ✅ Security review passed (if applicable)\n- ✅ Risks identified and mitigated\n- ✅ Timeline realistic and agreed upon\n- ⏳ Test strategy approved by QA\n- ⏳ Monitoring plan reviewed by SRE\n\n**Next Steps After Approval**:\n\n1. Create Epic in Jira (link in metadata)\n2. Break down into User Stories\n3. Begin Phase 1 implementation\n4. Schedule kickoff meeting with team\n```\n\n---\n\n## Validation Rules\n\n### Mandatory Section Checklist\n\nBefore finalizing TDD, ensure:\n\n- [ ] **Header**: Tech Lead, Team, Epic link present\n- [ ] **Context**: 2+ paragraphs describing background and domain\n- [ ] **Problem**: At least 2 specific problems identified with impact\n- [ ] **Scope**: Clear in-scope and out-of-scope items (min 3 each)\n- [ ] **Technical Solution**: Architecture diagram or description\n- [ ] **Technical Solution**: At least 1 API endpoint defined\n- [ ] **Risks**: At least 3 risks with impact\u002Fprobability\u002Fmitigation\n- [ ] **Implementation Plan**: Broken into phases with estimates\n\n### Critical Section Checklist (by project type)\n\n**If Payment\u002FAuth project**:\n\n- [ ] **Security**: Authentication method defined\n- [ ] **Security**: Encryption (at rest, in transit) specified\n- [ ] **Security**: PII handling approach documented\n- [ ] **Security**: Compliance requirements identified\n\n**If Production system**:\n\n- [ ] **Monitoring**: At least 3 metrics defined with thresholds\n- [ ] **Monitoring**: Alerts configured\n- [ ] **Rollback**: Rollback triggers defined\n- [ ] **Rollback**: Rollback steps documented\n\n**All projects**:\n\n- [ ] **Testing**: At least 2 test types defined (unit, integration, e2e)\n- [ ] **Testing**: Critical test scenarios listed\n\n## Output Format\n\n### When Creating TDD\n\n1. **Generate Markdown document**\n2. **Validate against checklists above**\n3. **Highlight any missing critical sections**\n4. **Provide summary to user**:\n\n```\n✅ TDD Created: \"[Project Name]\"\n\n**Sections Included**:\n✅ Mandatory (7\u002F7): All present\n✅ Critical (3\u002F4): Security, Testing, Monitoring\n⚠️ Missing: Rollback Plan (recommended for production)\n\n**Suggested Next Steps**:\n- Add Rollback Plan section (critical for production)\n- Review Security section with InfoSec team\n- Create Epic in Jira and link in metadata\n- Schedule TDD review meeting with stakeholders\n\nWould you like me to:\n1. Add the missing Rollback Plan section?\n2. Publish this TDD to Confluence?\n3. Create a Jira Epic for this project?\n```\n\n### Confluence Integration\n\nIf user wants to publish to Confluence:\n\n```\nI'll publish this TDD to Confluence.\n\nWhich space should I use?\n- Personal space (~557058...)\n- Team space (provide space key)\n\nShould I:\n- Create a new page\n- Update existing page (provide page ID or URL)\n```\n\nThen use Confluence Assistant skill to publish.\n\n## Common Anti-Patterns to Avoid\n\n### ❌ Vague Problem Statements\n\n**BAD**:\n\n```\n\nWe need to integrate with Stripe.\n\n```\n\n**GOOD**:\n\n```\n\n### Problems We're Solving\n\n- **Manual payment processing takes 2 hours\u002Fday**: Currently processing payments manually, costing $500\u002Fmonth in labor\n- **Cannot expand internationally**: Current payment processor only supports USD\n- **High cart abandonment (45%)**: Poor checkout UX causing revenue loss of $10k\u002Fmonth\n\n```\n\n### ❌ Undefined Scope\n\n**BAD**:\n\n```\n\nBuild payment integration with all features.\n\n```\n\n**GOOD**:\n\n```\n\n### ✅ In Scope (V1)\n\n- Trial subscriptions (14 days)\n- Single payment method per user\n- USD only\n- Cancel subscription\n\n### ❌ Out of Scope (V1)\n\n- Multiple payment methods\n- Multi-currency\n- Promo codes\n- Usage-based billing\n\n```\n\n### ❌ Missing Security for Payment Systems\n\n**BAD**:\n\n```\n\nNo security section for payment integration.\n\n```\n\n**GOOD**:\n\n```\n\n### Security Considerations (MANDATORY)\n\n**PCI DSS Compliance**:\n\n- Never store full card numbers (use Stripe tokens)\n- Never log CVV or full PAN\n- Use Stripe Elements for card input (PCI SAQ A)\n\n**Secrets Management**:\n\n- Store `STRIPE_SECRET_KEY` in environment variables\n- Rotate keys every 90 days\n- Never commit keys to git\n\n```\n\n### ❌ No Rollback Plan\n\n**BAD**:\n\n```\n\nWe'll deploy and hope it works.\n\n```\n\n**GOOD**:\n\n```\n\n### Rollback Plan\n\n**Triggers**:\n\n- Error rate > 5% → immediate rollback\n- Payment processing failures > 10% → immediate rollback\n\n**Steps**:\n\n1. Disable feature flag `STRIPE_INTEGRATION_ENABLED`\n2. Verify old payment processor is active\n3. Notify #engineering and #product\n4. Schedule post-mortem within 24h\n\n```\n\n## Important Notes\n\n- **Respect user's language** - Automatically detect and generate TDD in the same language as user's request\n- **Focus on architecture, not implementation** - Document decisions and contracts, not code\n- **High-level examples only** - Show API contracts, data schemas, diagrams (not CLI commands or code snippets)\n- **Always validate mandatory sections** - Don't let user skip them\n- **For payments\u002Fauth** - Security section is MANDATORY\n- **For production** - Monitoring and Rollback are MANDATORY\n- **Ask clarifying questions** - Don't guess missing information (ask in user's language)\n- **Be thorough but pragmatic** - Small projects don't need all 20 sections\n- **Update the document** - TDDs should evolve as the project progresses\n- **Use industry standards** - Reference Google, Amazon, RFC patterns\n- **Think about compliance** - GDPR, PCI DSS, HIPAA where applicable\n- **Test for longevity** - If implementation framework changes, TDD should still be valid\n\n## Example Prompts that Trigger This Skill\n\n### English\n\n- \"Create a TDD for Stripe integration\"\n- \"I need a technical design document for the new auth system\"\n- \"Write a design doc for the API redesign\"\n- \"Help me document the payment integration architecture\"\n- \"Create a tech spec for migrating to microservices\"\n\n### Portuguese\n\n- \"Crie um TDD para integração com Stripe\"\n- \"Preciso de um documento de design técnico para o novo sistema de autenticação\"\n- \"Escreva um design doc para o redesign da API\"\n- \"Me ajude a documentar a arquitetura de integração de pagamento\"\n- \"Crie uma especificação técnica para migração para microserviços\"\n\n### Spanish\n\n- \"Crea un TDD para integración con Stripe\"\n- \"Necesito un documento de diseño técnico para el nuevo sistema de autenticación\"\n- \"Escribe un design doc para el rediseño de la API\"\n- \"Ayúdame a documentar la arquitectura de integración de pagos\"\n- \"Crea una especificación técnica para migración a microservicios\"\n\n## References\n\n### Industry Standards\n\n- [Google Engineering Practices](https:\u002F\u002Fgoogle.github.io\u002Feng-practices\u002F)\n- [Google SRE Book](https:\u002F\u002Fsre.google\u002Fsre-book\u002Ftable-of-contents\u002F)\n- [OWASP Top 10](https:\u002F\u002Fowasp.org\u002Fwww-project-top-ten\u002F)\n- [Architecture Decision Records](https:\u002F\u002Fadr.github.io\u002F)\n\n```\n\n```\n",{},"main","def8531e65114c0fca8fb8551c1871ee0eed705c","skills\u002Ftech-leads-club\u002Fagent-skills\u002Fcreate-technical-design-doc",24,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub","https:\u002F\u002Fskillshub.wtf","https:\u002F\u002Fgithub.com\u002FComeOnOliver","AI & Blockchain Engineer\r\n","2026-06-24 22:07:19",{"source":7,"skillName":5,"commands":55,"prompt":65,"zipAvailable":66},[56,59,62],{"tool":57,"command":58},"npx","npx skills add ComeOnOliver\u002Fskillshub --skill create-technical-design-doc",{"tool":60,"command":61},"bunx","bunx skills add ComeOnOliver\u002Fskillshub --skill create-technical-design-doc",{"tool":63,"command":64},"pnpm","pnpm dlx skills add ComeOnOliver\u002Fskillshub --skill create-technical-design-doc","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Ftech-leads-club\u002Fagent-skills\u002Fcreate-technical-design-doc\u002FSKILL.md",true,[],[69,79,89,98,104,111],{"skillNo":70,"name":71,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":75,"publishedAt":41},"01M6FKJN13GMG4KY57J3QD8GY5","model-hierarchy-skill","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzscole\u002Fmodel-hierarchy-skill\u002Fmodel-hierarchy-skill\u002FSKILL.md",[74],{"categoryNo":26,"categoryName":27,"taxonomyType":20,"taxonomyTypeDesc":21},[76,77,78],"model","model hierarchy","model hierarchy skill",{"skillNo":80,"name":81,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":85,"publishedAt":41},"01M6FKJJJ6GCAMR4PPPRD12M5X","zoom-mcp","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-mcp\u002FSKILL.md",[84],{"categoryNo":26,"categoryName":27,"taxonomyType":20,"taxonomyTypeDesc":21},[86,87,88],"MCP","zoom","zoom mcp",{"skillNo":90,"name":91,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":41},"01M6FKJE3KYT3KPEZMEEHYKA6K","zoom-apps-sdk","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-apps-sdk\u002FSKILL.md",[],[95,96,97,87],"sdk","zoom apps sdk","apps",{"skillNo":99,"name":100,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":41},"01M6FKJ9EDH9Q5VWDF8HAJRSP0","windows","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwindows\u002FSKILL.md",[],[100],{"skillNo":105,"name":106,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":110,"publishedAt":41},"01M6FKJ666BEEFC3AE9GJ72Q93","whiteboard","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwhiteboard\u002FSKILL.md",[109],{"categoryNo":26,"categoryName":27,"taxonomyType":20,"taxonomyTypeDesc":21},[106],{"skillNo":112,"name":113,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":114,"categories":115,"keywords":116,"publishedAt":41},"01M6FKJ21WFCDGTJQ2Q91T9DVW","websockets","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwebsockets\u002FSKILL.md",[],[113]]