tech-design-doc_skill

Overview

This skill generates clear, actionable technical design documents with a scalable structure, diagrams, and implementation details. It adapts the template to small, medium, and large scopes and produces materials ready for review, handoff, or implementation planning. Default language is English unless you request Chinese.

How this skill works

The skill inspects provided context: feature description, code pointers, and intended scope, then selects a template level (Small/Medium/Large). It produces sections for TL;DR, background, solution analysis, detailed design, implementation plan, migration strategy, risks, and references, and embeds Mermaid diagrams where helpful. Before finalizing, it runs a verification checklist to ensure decisions, trade-offs, and actionable tasks are present.

When to use it

• Designing a new feature or service from scratch
• Preparing an ADR/RFC or architecture decision record
• Planning a cross-team API change or integration
• Documenting a refactor or optimization with rollout steps
• Handing off design work to implementation or QA

Best practices

• Start by assessing complexity and choose the template scale (Small/Medium/Large)
• Gather concrete code references and dependency notes before writing design details
• Include 3–5 TL;DR bullets so reviewers grasp intent quickly
• Compare at least two solution options and document trade-offs
• Add Mermaid diagrams for architecture, sequence, or state flows to clarify interactions
• Provide a phased implementation plan with migration steps and rollback criteria

Example use cases

• Design a new microservice and its API surface with data model and migration plan
• Produce an ADR comparing two caching strategies with performance and cost trade-offs
• Document a refactor that touches multiple modules and requires a rollout plan
• Create a detailed design for a backend feature including sequence diagrams and task checklist
• Convert exploratory notes and PR discussion into a formal design document for stakeholder review