Technical Design Document Creator

Purpose

Use this skill to create design docs that:

• Align stakeholders on what is being built and why.
• Capture architecture and trade-offs explicitly.
• Provide a durable reference for implementation and future changes.

When to Use

• Cross-team or cross-service changes.
• New user-facing features with non-trivial backend impact.
• Data model changes, migrations, and new storage systems.
• Major performance, reliability, or security projects.

Design Doc Structure

A good design doc should cover:

1. Overview

   • One-paragraph summary of the problem and proposed solution.
   • Expected impact at a high level.

2. Background and Context

   • Current behavior and pain points.
   • Relevant metrics, incidents, or user feedback.
   • Links to prior designs or ADRs.

3. Goals and Non-Goals

   • Goals: What success looks like.
   • Non-goals: Explicitly out-of-scope aspects to prevent scope creep.

4. Requirements and Constraints

   • Functional requirements.
   • Non-functional: performance, availability, security, privacy, compliance, cost, deadlines.

5. Proposed Solution

   • Architecture diagrams and component overviews.
   • Data flow and control flow (sequence diagrams where useful).
   • Key algorithms or logic at a high level.

6. Alternatives Considered

   • Briefly describe 2–3 options and why they were rejected.
   • Include “do nothing” when relevant.

7. Impact Analysis

   • On existing systems, APIs, clients, and data.
   • Operational impact: on-call, runbooks, observability.
   • Risks and mitigations.

8. Testing and Validation

   • Unit, integration, and end-to-end testing strategy.
   • Load/performance testing plans.
   • Rollback and failure drills, if applicable.

9. Rollout Plan

   • Milestones and phases.
   • Feature flagging or staged rollout strategy.
   • Monitoring during rollout; success criteria.

10. Open Questions and Future Work

    • Areas needing further exploration.
    • Potential follow-ups that are explicitly out of the current scope.

Usage Guidance

• Optimize for clarity over completeness. If a section is not applicable, say why.
• Draw diagrams where they clarify non-trivial flows or boundaries.
• Keep the document living: update when significant decisions or constraints change.

Examples of Good Prompts

• “Create a full design doc using this template for the following feature description.”
• “Given this high-level idea, flesh it out into a design doc with at least two alternative solutions.”
• “Review this existing design doc using the template; identify missing sections and key risks.”