Technical Design Document Skill

Create structured technical design documents that communicate system behavior, implementation approach, and acceptance criteria.

Workflow

1. Gather context: Understand the feature/system scope, constraints, and goals
2. Draft structure: Use template from references/template.md
3. Fill sections: Work through each section, asking clarifying questions as needed
4. Review: Ensure acceptance criteria are testable and implementation outline is actionable

Template

See references/template.md for the full template structure and section guidelines.

Core sections:

• Context and motivation: Problem statement, goals, non-goals
• Implementation considerations: Constraints and design principles
• High-level behavior: End-to-end system behavior
• Domain-specific sections: Adapt to feature type (discovery, validation, API, state, rendering)
• Error handling and UX: Error surfacing and recovery
• Future-proofing: Design for extensibility
• Implementation outline: Step-by-step approach
• Testing approach: Unit, integration, manual tests
• Acceptance criteria: Testable conditions for “done”

Writing Guidelines

• Use --- underlines for section headers (Setext style)
• Write in present tense for behavior (“loads”, “validates”, “returns”)
• Be specific: “max 100 chars” not “reasonable length”
• Include concrete examples where behavior varies
• Non-goals are as important as goals – prevent scope creep
• Acceptance criteria must be verifiable, not subjective