---
name: technical-design-document
description: "Drafts a technical design document with goals, non-goals, the proposed design, alternatives, risks and rollout, ready for review by other engineers. Use when an engineer is about to start a substantial project and needs a design doc with goals, non-goals, alternatives, risks and rollout for review. Do not use for recording a single decision or writing user-facing documentation. Related topics: coding, writing."
---

# Technical Design Document

Drafts a technical design document with goals, non-goals, the proposed design, alternatives, risks and rollout, ready for review by other engineers.

## When to use

Use this skill when an engineer is about to start a substantial project and needs a design doc with goals, non-goals, alternatives, risks and rollout for review. Do not use it for recording a single decision or writing user-facing documentation.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. State the problem with measurable goals and write non-goals that fence the scope.
3. Describe the design through components, data flow, interfaces, data changes and failure behaviour at reviewer level.
4. Add at least two alternatives, each with the specific reason it was not chosen.
5. Cover security, testing, observability and a rollout order with a way to back out.
6. List risks and open questions with owners, and flag every assumption the author must confirm.

## Inputs

- **Project name** (free text, e.g. "Short name")
- **Problem** (longer free text)
- **Scale and constraints** (longer free text)
- **Rough approach** (longer free text)
- **Systems it touches** (longer free text)
- **Reviewers** (free text, e.g. "Who needs to sign off")
- **Document length** (choose one: One page, Three pages, Full detail)

## Output

A design document sized to the chosen length with these sections in order: problem, goals, non-goals, design, alternatives, risks, rollout, open questions and milestones.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Technical Design Document

Draft a design doc for this project.

- Project name: {{Project name}}
- Problem: {{Problem}}
- Scale and constraints: {{Scale and constraints}}
- Rough approach: {{Rough approach}}
- Systems it touches: {{Systems it touches}}
- Reviewers: {{Reviewers}}
- Document length: {{Document length}}

Write it so a reviewer can disagree with it precisely. Start with the problem and measurable goals, then explicit non-goals that stop scope creep. Describe the design at the level the reviewers need: components, data flow, interfaces, data model changes and failure behaviour, with a diagram described in text if useful. Include at least two alternatives with the reason each was not chosen. Add sections for security and privacy, testing, observability, and migration or rollout with the order of steps and how to back out. List risks with likelihood, impact and mitigation, and open questions that need an answer before work starts, each with an owner. Close with a rough milestone list. Use plain language and numbers wherever the input allows, and flag any assumption you made that the author should confirm.

## Pitfalls

- Skipping non-goals, so reviewers debate features the project never meant to cover.
- Presenting one design with no alternatives, which turns review into approval theatre.
- Describing the happy path only, when most review comments concern failure and migration.