Technical Design Doc Creator

Technical Design Doc Creator

Overview

This public intake copy packages packages/skills-catalog/skills/(creation)/create-technical-design-doc from https://github.com/tech-leads-club/agent-skills into the native Omni Skills editorial shape without hiding its origin.

Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.

This intake keeps the copied upstream files intact and uses the external_source block in metadata.json plus ORIGIN.md as the provenance anchor for review.

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.

Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: Language Adaptation, High-Level vs Implementation Details, Document Structure, Project Size Adaptation, Section Templates, Context.

When to Use This Skill

Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.

• 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

Operating Table

Workflow

This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.

1. Tech Lead / Owner
2. Team members
3. Problem description (what/why/impact)
4. What is in scope
5. What is out of scope
6. High-level solution approach
7. At least 3 risks

Imported Workflow Notes

Imported: Interactive Workflow

Step 1: Initial Gathering

Use AskQuestion tool to collect basic information:

{
  "title": "TDD Project Information",
  "questions": [
    {
      "id": "project_name",
      "prompt": "What is the name of the feature/integration/project?",
      "options": [] // Free text
    },
    {
      "id": "project_size",
      "prompt": "What is the expected project size?",
      "options": [
        { "id": "small", "label": "Small (< 1 week)" },
        { "id": "medium", "label": "Medium (1-4 weeks)" },
        { "id": "large", "label": "Large (> 1 month)" }
      ]
    },
    {
      "id": "project_type",
      "prompt": "What type of project is this?",
      "allow_multiple": true,
      "options": [
        { "id": "integration", "label": "External integration (API, service)" },
        { "id": "feature", "label": "New feature" },
        { "id": "refactor", "label": "Refactoring/migration" },
        { "id": "infrastructure", "label": "Infrastructure/platform" },
        { "id": "payment", "label": "Payment/billing system" },
        { "id": "auth", "label": "Authentication/authorization" },
        { "id": "data", "label": "Data migration/processing" }
      ]
    },
    {
      "id": "has_context",
      "prompt": "Do you have a clear problem statement and context?",
      "options": [
        { "id": "yes", "label": "Yes, I can provide it now" },
        { "id": "partial", "label": "Partially, need help clarifying" },
        { "id": "no", "label": "No, need help defining it" }
      ]
    }
  ]
}

Step 2: Validate Mandatory Information

Based on answers, check if user can provide:

MANDATORY fields to ask if missing:

• Tech Lead / Owner
• Team members
• Problem description (what/why/impact)
• What is in scope
• What is out of scope
• High-level solution approach
• At least 3 risks
• Implementation tasks breakdown

Ask using AskQuestion or natural conversation IN THE USER'S LANGUAGE:

English Example:

I need the following information to create the TDD:

1. **Problem Statement**:
   - What problem are we solving?
   - Why is this important now?
   - What happens if we don't solve it?

2. **Scope**:
   - What WILL be delivered in this project?
   - What will NOT be included (out of scope)?

3. **Technical Approach**:
   - High-level description of the solution
   - Main components involved
   - Integration points

Can you provide this information?

Portuguese Example:

Preciso das seguintes informações para criar o TDD:

1. **Definição do Problema**:
   - Que problema estamos resolvendo?
   - Por que isso é importante agora?
   - O que acontece se não resolvermos?

2. **Escopo**:
   - O que SERÁ entregue neste projeto?
   - O que NÃO será incluído (fora do escopo)?

3. **Abordagem Técnica**:
   - Descrição de alto nível da solução
   - Principais componentes envolvidos
   - Pontos de integração

Você pode fornecer essas informações?

Step 3: Check for Critical Sections

Based on project_type, determine if critical sections are mandatory:

If critical sections are missing, ASK IN THE USER'S LANGUAGE:

English:

This is a [payment/auth/production] system. These sections are CRITICAL:

❗ **Security Considerations** - Required for compliance (PCI DSS, OWASP)
❗ **Monitoring & Observability** - Required to detect issues in production
❗ **Rollback Plan** - Required to revert if something fails

Can you provide:
1. Security requirements (auth, encryption, PII handling)?
2. What metrics will you monitor?
3. How will you rollback if something goes wrong?

Portuguese:

Este é um sistema de [pagamento/autenticação/produção]. Estas seções são CRÍTICAS:

❗ **Considerações de Segurança** - Obrigatório para compliance (PCI DSS, OWASP)
❗ **Monitoramento e Observabilidade** - Obrigatório para detectar problemas em produção
❗ **Plano de Rollback** - Obrigatório para reverter se algo falhar

Você pode fornecer:
1. Requisitos de segurança (autenticação, encriptação, tratamento de PII)?
2. Quais métricas você vai monitorar?
3. Como você fará rollback se algo der errado?

Step 4: Offer Suggested Sections

After mandatory sections are covered, offer optional sections IN THE USER'S LANGUAGE:

English:

I can also add these sections to make the TDD more complete:

📊 **Success Metrics** - How will you measure success?
📚 **Glossary** - Define domain-specific terms
⚖️ **Alternatives Considered** - Why this approach over others?
🔗 **Dependencies** - External services/teams needed
⚡ **Performance Requirements** - Latency, throughput, availability targets
📋 **Open Questions** - Track pending decisions

Would you like me to add any of these now? (You can add them later)

Portuguese:

Também posso adicionar estas seções para tornar o TDD mais completo:

📊 **Métricas de Sucesso** - Como você vai medir o sucesso?
📚 **Glossário** - Definir termos específicos do domínio
⚖️ **Alternativas Consideradas** - Por que esta abordagem ao invés de outras?
🔗 **Dependências** - Serviços/times externos necessários
⚡ **Requisitos de Performance** - Latência, throughput, disponibilidade
📋 **Questões em Aberto** - Rastrear decisões pendentes

Gostaria que eu adicionasse alguma dessas agora? (Você pode adicionar depois)

Step 5: Generate Document

Generate the TDD in Markdown format following the templates below.

Step 6: Offer Confluence Integration

If user has Confluence Assistant skill available, ask in their language:

English:

Would you like me to publish this TDD to Confluence?
- I can create a new page in your space
- Or update an existing page

Portuguese:

Gostaria que eu publicasse este TDD no Confluence?
- Posso criar uma nova página no seu espaço
- Ou atualizar uma página existente

Imported: 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:

Examples

Example 1: Ask for the upstream workflow directly

Use @technical-design-doc-creator to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.

Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.

Example 2: Ask for a provenance-grounded review

Review @technical-design-doc-creator against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.

Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.

Example 3: Narrow the copied support files before execution

Use @technical-design-doc-creator for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.

Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.

Example 4: Build a reviewer packet

Review @technical-design-doc-creator using the copied upstream files plus provenance, then summarize any gaps before merge.

Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.

Best Practices

Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.

• Header: Tech Lead, Team, Epic link present
• Context: 2+ paragraphs describing background and domain
• Problem: At least 2 specific problems identified with impact
• Scope: Clear in-scope and out-of-scope items (min 3 each)
• Technical Solution: Architecture diagram or description
• Technical Solution: At least 1 API endpoint defined
• Risks: At least 3 risks with impact/probability/mitigation

Imported Operating Notes

Imported: Validation Rules

Mandatory Section Checklist

Before finalizing TDD, ensure:

• Header: Tech Lead, Team, Epic link present
• Context: 2+ paragraphs describing background and domain
• Problem: At least 2 specific problems identified with impact
• Scope: Clear in-scope and out-of-scope items (min 3 each)
• Technical Solution: Architecture diagram or description
• Technical Solution: At least 1 API endpoint defined
• Risks: At least 3 risks with impact/probability/mitigation
• Implementation Plan: Broken into phases with estimates

Critical Section Checklist (by project type)

If Payment/Auth project:

• Security: Authentication method defined
• Security: Encryption (at rest, in transit) specified
• Security: PII handling approach documented
• Security: Compliance requirements identified

If Production system:

• Monitoring: At least 3 metrics defined with thresholds
• Monitoring: Alerts configured
• Rollback: Rollback triggers defined
• Rollback: Rollback steps documented

All projects:

• Testing: At least 2 test types defined (unit, integration, e2e)
• Testing: Critical test scenarios listed

Troubleshooting

Problem: The operator skipped the imported context and answered too generically

Symptoms: The result ignores the upstream workflow in packages/skills-catalog/skills/(creation)/create-technical-design-doc, fails to mention provenance, or does not use any copied source files at all. Solution: Re-open metadata.json, ORIGIN.md, and the most relevant copied upstream files. Check the external_source block first, then restate the provenance before continuing.

Problem: The imported workflow feels incomplete during review

Symptoms: Reviewers can see the generated SKILL.md, but they cannot quickly tell which references, examples, or scripts matter for the current task. Solution: Point at the exact copied references, examples, scripts, or assets that justify the path you took. If the gap is still real, record it in the PR instead of hiding it.

Problem: The task drifted into a different specialization

Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better. Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.

Imported Troubleshooting Notes

Imported: Problem Statement & Motivation

Problems We're Solving

• Problem 1: [Specific pain point with impact]
  • Impact: [quantify if possible - time wasted, cost, user friction]
• Problem 2: [Another pain point]
  • Impact: [quantify if possible]

Why Now?

• [Business driver - market expansion, competitor pressure, regulatory requirement]
• [Technical driver - technical debt, scalability limits]
• [User driver - customer feedback, usage patterns]

Impact of NOT Solving

• Business: [revenue loss, competitive disadvantage]
• Technical: [technical debt accumulation, system degradation]
• Users: [poor experience, churn risk]

**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?"

---

### 4. Scope (MANDATORY)

```markdown

## Related Skills

- `@accessibility` - Use when the work is better handled by that native specialization after this imported skill establishes context.
- `@ai-cold-outreach` - Use when the work is better handled by that native specialization after this imported skill establishes context.
- `@ai-pricing` - Use when the work is better handled by that native specialization after this imported skill establishes context.
- `@ai-sdr` - Use when the work is better handled by that native specialization after this imported skill establishes context.

## Additional Resources

Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.

| Resource family | What it gives the reviewer | Example path |
| --- | --- | --- |
| `references` | copied reference notes, guides, or background material from upstream | `references/n/a` |
| `examples` | worked examples or reusable prompts copied from upstream | `examples/n/a` |
| `scripts` | upstream helper scripts that change execution or validation | `scripts/n/a` |
| `agents` | routing or delegation notes that are genuinely part of the imported package | `agents/n/a` |
| `assets` | supporting assets or schemas copied from the source package | `assets/n/a` |

- [README.md](README.md)

### Imported Reference Notes

#### Imported: 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

#### Imported: References

### Industry Standards

- [Google Engineering Practices](https://google.github.io/eng-practices/)
- [Google SRE Book](https://sre.google/sre-book/table-of-contents/)
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [Architecture Decision Records](https://adr.github.io/)

#### Imported: 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)

````markdown
**Rollback Steps**:

```bash
curl -X PATCH https://api.launchdarkly.com/flags/FEATURE_X \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"enabled": false}'

nx db:rollback billing

✅ GOOD (High-Level Decision)

**Rollback Steps**:
1. Disable feature flag via feature flag service dashboard
2. Revert database schema using down migration
3. Verify system returns to previous state
4. Monitor error rates to confirm rollback success

❌ BAD (Implementation Code)

**Service Implementation**:

```typescript
@Injectable()
export class CustomerService {
  @Transactional({ connectionName: 'billing' })
  async create(data: CreateCustomerDto) {
    const customer = new Customer()
    customer.email = data.email
    return this.repository.save(customer)
  }
}
```

#### ✅ GOOD (High-Level Structure)

```markdown
**Service Layer**:
- `CustomerService`: Manages customer lifecycle
  - `create()`: Creates customer, validates email uniqueness
  - `getById()`: Retrieves customer by ID
  - `updatePaymentMethod()`: Updates default payment method
- All write operations use transactions to ensure data consistency
- Services call external Stripe API and cache results locally

Guideline: Ask "Will This Change?"

Before adding detail to TDD, ask:

• "If we change frameworks, does this detail still apply?"

  • YES → Include (it's an architectural decision)
  • NO → Exclude (it's implementation detail)

• "Can someone implement this differently and still meet the requirement?"

  • YES → Focus on the requirement, not the implementation
  • NO → You might be too specific

Goal: TDD should survive implementation changes. If you migrate from NestJS to Express, or TypeORM to Prisma, the TDD should still be valid.

Imported: Document Structure

Mandatory Sections (Must Have)

These sections are required. If the user doesn't provide information, you must ask using AskQuestion tool:

1. Header & Metadata
2. Context
3. Problem Statement & Motivation
4. Scope (In Scope / Out of Scope)
5. Technical Solution
6. Risks
7. Implementation Plan

Critical Sections (Ask if Missing)

These are highly recommended especially for:

• Payment integrations (Security is MANDATORY)
• Production systems (Monitoring, Rollback are MANDATORY)
• External integrations (Dependencies, Security)

8. Security Considerations (MANDATORY for payments/auth/PII)
9. Testing Strategy
10. Monitoring & Observability
11. Rollback Plan

Suggested Sections (Offer to User)

Ask user: "Would you like to add these sections now or later?"

12. Success Metrics
13. Glossary & Domain Terms
14. Alternatives Considered
15. Dependencies
16. Performance Requirements
17. Migration Plan (if applicable)
18. Open Questions
19. Roadmap / Timeline
20. Approval & Sign-off

Imported: Project Size Adaptation

Use this heuristic to determine project complexity:

Small Project (< 1 week)

Use sections: 1, 2, 3, 4, 5, 6, 7, 9

Skip: Alternatives, Migration Plan, Approval

Medium Project (1-4 weeks)

Use sections: 1-11, 15, 18

Offer: Success Metrics, Glossary, Alternatives, Performance

Large Project (> 1 month)

Use all sections (1-20)

Critical: All mandatory + critical sections must be detailed

Imported: Section Templates

1. Header & Metadata (MANDATORY)

# TDD - [Project/Feature Name]

| Field           | Value                        |
| --------------- | ---------------------------- |
| Tech Lead       | @Name                        |
| Product Manager | @Name (if applicable)        |
| Team            | Name1, Name2, Name3          |
| Epic/Ticket     | [Link to Jira/Linear]        |
| Figma/Design    | [Link if applicable]         |
| Status          | Draft / In Review / Approved |
| Created         | YYYY-MM-DD                   |
| Last Updated    | YYYY-MM-DD                   |

If user doesn't provide: Ask for Tech Lead, Team members, and Epic link.

2. Context (MANDATORY)

#### Imported: Context

[2-4 paragraph description of the project]

**Background**:
What is the current state? What system/feature does this relate to?

**Domain**:
What business domain is this part of? (e.g., billing, authentication, content delivery)

**Stakeholders**:
Who cares about this project? (users, business, compliance, etc.)

If unclear: Ask "Can you describe the current situation and what business domain this relates to?"

3. Problem Statement & Motivation (MANDATORY)

#### Imported: Scope

### ✅ In Scope (V1 - MVP)

Explicit list of what WILL be delivered:

- Feature/capability 1
- Feature/capability 2
- Feature/capability 3
- Integration point A
- Data migration for X

### ❌ Out of Scope (V1)

Explicit list of what will NOT be included in this phase:

- Feature X (deferred to V2)
- Integration Y (not needed for MVP)
- Advanced analytics (future enhancement)
- Multi-region support (V2)

### 🔮 Future Considerations (V2+)

What might come later:

- Feature A (user demand dependent)
- Feature B (after V1 validation)

If user doesn't define: Ask "What are the must-haves for V1? What can wait for later versions?"

5. Technical Solution (MANDATORY)

#### Imported: Technical Solution

### Architecture Overview

[High-level description of the solution]

**Key Components**:

- Component A: [responsibility]
- Component B: [responsibility]
- Component C: [responsibility]

**Architecture Diagram**:

[Include Mermaid diagram, PlantUML, or link to diagram]

```mermaid
graph LR
    A[Frontend] -->|HTTP| B[API Gateway]
    B -->|GraphQL| C[Backend Service]
    C -->|REST| D[External API]
    C -->|Write| E[(Database)]
```

Data Flow

1. Step 1: User action → Frontend
2. Step 2: Frontend → API Gateway (POST /resource)
3. Step 3: API Gateway → Service Layer
4. Step 4: Service → External API (if applicable)
5. Step 5: Service → Database (persist)
6. Step 6: Response → Frontend

APIs & Endpoints

Example Request/Response:

// POST /api/v1/resource
{
  "name": "Example",
  "type": "standard"
}

// Response 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Example",
  "type": "standard",
  "status": "active",
  "createdAt": "2026-02-04T10:00:00Z"
}

Database Changes

New Tables:

• {ModuleName}{EntityName} - [description]
  • Primary fields: id, userId, name, status
  • Timestamps: createdAt, updatedAt
  • Indexes: userId, status (for query performance)

Schema Changes (if modifying existing):

• Add column newField to ExistingTable
  • Type: [varchar/integer/jsonb/etc.]
  • Constraints: [nullable/unique/foreign key]

Migration Strategy:

• Generate migration from schema changes
• Test migration on staging environment first
• Run during low-traffic window
• Have rollback migration ready

Data Backfill (if needed):

• Affected records: Estimate quantity
• Processing time: Estimate duration for data migration
• Validation: How to verify data integrity after backfill

**If user provides vague description**: Ask "What are the main components? How does data flow through the system? What APIs will be created/modified?"

---

### 6. Risks (MANDATORY)

```markdown

#### Imported: Risks

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| External API downtime | High | Medium | Implement circuit breaker, cache responses, fallback to degraded mode |
| Data migration failure | High | Low | Test on staging copy, run dry-run first, have rollback script ready |
| Performance degradation | Medium | Medium | Load test before deployment, implement caching, monitor latency |
| Security vulnerability | High | Low | Security review, penetration testing, follow OWASP guidelines |
| Scope creep | Medium | High | Strict scope definition, change request process, regular stakeholder alignment |

**Risk Scoring**:
- **Impact**: High (system down, data loss) / Medium (degraded UX) / Low (minor inconvenience)
- **Probability**: High (>50%) / Medium (20-50%) / Low (<20%)

If user provides < 3 risks: Ask "What could go wrong? Consider: external dependencies, data integrity, performance, security, scope changes."

7. Implementation Plan (MANDATORY)

#### Imported: Implementation Plan

| Phase                 | Task              | Description                            | Owner   | Status | Estimate |
| --------------------- | ----------------- | -------------------------------------- | ------- | ------ | -------- |
| **Phase 1 - Setup**   | Setup credentials | Obtain API keys, configure environment | @Dev1   | TODO   | 1d       |
|                       | Database setup    | Create schema, configure datasource    | @Dev1   | TODO   | 1d       |
| **Phase 2 - Core**    | Entities & repos  | Create TypeORM entities, repositories  | @Dev2   | TODO   | 3d       |
|                       | Services          | Implement business logic services      | @Dev2   | TODO   | 4d       |
| **Phase 3 - APIs**    | REST endpoints    | Create controllers, DTOs               | @Dev3   | TODO   | 3d       |
|                       | Integration       | Integrate with external API            | @Dev1   | TODO   | 3d       |
| **Phase 4 - Testing** | Unit tests        | Test services and repositories         | @Team   | TODO   | 2d       |
|                       | E2E tests         | Test full flow                         | @Team   | TODO   | 3d       |
| **Phase 5 - Deploy**  | Staging deploy    | Deploy to staging, smoke test          | @DevOps | TODO   | 1d       |
|                       | Production deploy | Phased rollout to production           | @DevOps | TODO   | 1d       |

**Total Estimate**: ~20 days (4 weeks)

**Dependencies**:

- Must complete Phase N before Phase N+1
- External API access required before Phase 3
- Security review required before Phase 5

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?"

8. Security Considerations (CRITICAL for payments/auth/PII)

#### Imported: Security Considerations

### Authentication & Authorization

- **Authentication**: How users prove identity
  - Example: JWT tokens, OAuth 2.0, session-based
- **Authorization**: What authenticated users can access
  - Example: Role-based (RBAC), Attribute-based (ABAC)
  - Ensure users can only access their own resources

### Data Protection

**Encryption**:

- **At Rest**: Database encryption enabled (AES-256)
- **In Transit**: TLS 1.3 for all API communication
- **Secrets**: Store API keys in environment variables / secret manager (AWS Secrets Manager, HashiCorp Vault)

**PII Handling**:

- What PII is collected: [email, name, payment info]
- Legal basis: [consent, contract, legitimate interest]
- Retention: [how long data is kept]
- Deletion: [GDPR right to be forgotten implementation]

### Compliance Requirements

| Regulation  | Requirement                        | Implementation                                    |
| ----------- | ---------------------------------- | ------------------------------------------------- |
| **GDPR**    | Data protection, right to deletion | Implement data export/deletion endpoints          |
| **PCI DSS** | No storage of card data            | Use Stripe tokenization, never store CVV/full PAN |
| **LGPD**    | Brazil data protection             | Same as GDPR compliance                           |

### Security Best Practices

- ✅ Input validation on all endpoints
- ✅ SQL injection prevention (parameterized queries)
- ✅ XSS prevention (sanitize user input, CSP headers)
- ✅ CSRF protection (tokens for state-changing operations)
- ✅ Rate limiting (e.g., 10 req/min per user, 100 req/min per IP)
- ✅ Audit logging (log all sensitive operations)

### Secrets Management

**API Keys**:

- Storage: Environment variables or secret management service
- Rotation: Define rotation policy (e.g., every 90 days)
- Access: Backend services only, never exposed to frontend
- Examples: Stripe keys, database credentials, API tokens

**Webhook Signatures**:

- Validate webhook signatures from external services
- Reject requests without valid signature headers
- Log invalid signature attempts for security monitoring

If missing and project involves payments/auth: Ask "This is a [payment/auth] 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)?"

9. Testing Strategy (CRITICAL)

#### Imported: Testing Strategy

| Test Type             | Scope                    | Coverage Target          | Approach             |
| --------------------- | ------------------------ | ------------------------ | -------------------- |
| **Unit Tests**        | Services, repositories   | > 80%                    | Jest with mocks      |
| **Integration Tests** | API endpoints + database | Critical paths           | Supertest + test DB  |
| **E2E Tests**         | Full user flows          | Happy path + error cases | Playwright           |
| **Contract Tests**    | External API integration | API contract validation  | Pact or manual mocks |
| **Load Tests**        | Performance under load   | Baseline performance     | k6 or Artillery      |

### Test Scenarios

**Unit Tests**:

- ✅ Service business logic (create, update, delete)
- ✅ Repository query methods
- ✅ Error handling (throw correct exceptions)
- ✅ Edge cases (null inputs, invalid data)

**Integration Tests**:

- ✅ POST `/api/v1/resource` → creates in DB
- ✅ GET `/api/v1/resource/:id` → returns correct data
- ✅ DELETE `/api/v1/resource/:id` → removes from DB
- ✅ Invalid input → returns 400 Bad Request
- ✅ Unauthorized access → returns 401/403

**E2E Tests**:

- ✅ User creates resource → success flow
- ✅ User tries to access another user's resource → denied
- ✅ External API fails → graceful degradation
- ✅ Database connection lost → proper error handling

**Load Tests**:

- Target: 100 req/s sustained, 500 req/s peak
- Monitor: Latency (p50, p95, p99), error rate, throughput
- Pass criteria: p95 < 500ms, error rate < 1%

### Test Data Management

- Use factories for test data (e.g., `@faker-js/faker`)
- Seed test database with realistic data
- Clean up test data after each test
- Use separate test database (never use production)

If missing: Ask "How will you test this? What test types are needed (unit, integration, e2e)? What are critical test scenarios?"

10. Monitoring & Observability (CRITICAL for production)

#### Imported: Monitoring & Observability

### Metrics to Track

| Metric                    | Type       | Alert Threshold   | Dashboard          |
| ------------------------- | ---------- | ----------------- | ------------------ |
| `api.latency`             | Latency    | p95 > 1s for 5min | DataDog / Grafana  |
| `api.error_rate`          | Error rate | > 1% for 5min     | DataDog / Grafana  |
| `external_api.latency`    | Latency    | p95 > 2s for 5min | DataDog            |
| `external_api.errors`     | Counter    | > 5 in 1min       | PagerDuty          |
| `database.query_time`     | Duration   | p95 > 100ms       | DataDog            |
| `webhook.processing_time` | Duration   | > 5s              | Internal Dashboard |

### Structured Logging

**Log Format** (JSON):

```json
{
  "level": "info",
  "timestamp": "2026-02-04T10:00:00Z",
  "message": "Resource created",
  "context": {
    "userId": "user-123",
    "resourceId": "res-456",
    "action": "create",
    "duration_ms": 45
  }
}
```

What to Log:

• ✅ All API requests (method, path, status, duration)
• ✅ External API calls (endpoint, status, duration)
• ✅ Database queries (slow queries > 100ms)
• ✅ Errors and exceptions (stack trace, context)
• ✅ Business events (resource created, payment processed)

What NOT to Log:

• ❌ Passwords, API keys, secrets
• ❌ Full credit card numbers
• ❌ Sensitive PII (redact or hash)

Alerts

Dashboards

Operational Dashboard:

• Request rate (per endpoint)
• Error rate (overall and per endpoint)
• Latency (p50, p95, p99)
• External API health
• Database performance

Business Dashboard:

• Resources created (count per day)
• Active users
• Conversion metrics (if applicable)

**If missing for production system**: Ask "How will you monitor this in production? What metrics matter? What alerts do you need?"

---

### 11. Rollback Plan (CRITICAL for production)

```markdown

#### Imported: Rollback Plan

### Deployment Strategy

- **Feature Flag**: `FEATURE_X_ENABLED` (LaunchDarkly / custom)
- **Phased Rollout**:
  - Phase 1: 5% of traffic (1 day)
  - Phase 2: 25% of traffic (1 day)
  - Phase 3: 50% of traffic (1 day)
  - Phase 4: 100% of traffic

- **Canary Deployment**: Deploy to 1 instance first, monitor for 1h before full rollout

### Rollback Triggers

| Trigger | Action |
|---------|--------|
| Error rate > 5% for 5 minutes | **Immediate rollback** - disable feature flag |
| Latency > 3s (p95) for 10 minutes | **Investigate** - rollback if no qu

…(truncated)