/tdd-writer

name: tdd-writer
description: "Draft comprehensive Technical Design Documents. Analyzes codebase, fetches ticket/design/doc context via MCP. Every technical claim is verified against actual code. Unverified information is explicitly marked. Use when the user wants to write a TDD, create a technical design document, plan a large engineering project, or says 'write a TDD'."

TDD Writer

Draft Technical Design Documents for staging up large or complex projects. A TDD is a communication tool: a reader who has never seen the work should be able to read it start to finish and come away understanding **what** you're proposing, **why**, and **how** it will be built. It is not a form to fill in, and it is not a checklist with the prose removed.

**REQUIRED BACKGROUND:** Invoke `/flagrare:write-docs` before drafting. This skill owns *what a TDD must cover and how to verify it*; write-docs owns *how to make the prose readable*. The single most common failure of an AI-drafted TDD is the "medicine sheet", every section flattened into terse bullets, no causality, nothing a human wants to read. The craft layer in write-docs is the antidote, and the section "Writing the document" below applies it specifically to TDDs. Read both; do not skip the handoff.

---

When to Use

• Projects estimated at 2+ weeks
• Complex features with multiple components
• Architectural changes affecting multiple services
• Features requiring cross-team coordination
• User says "write a TDD", "design doc", "technical design"

---

No Assumptions Policy

**Never assume, imply, or hallucinate ANY technical information.**

Every piece of information about architecture, code, systems, services, data models, and APIs must be: 1. Verified by reading actual source code 2. Confirmed via MCP tools (Jira, Confluence, Notion, Figma) 3. Double-checked against the actual codebase

When Information is Unknown

Use these markers:

[UNKNOWN: Brief description of what's missing]
[NEEDS VERIFICATION: What needs to be checked and where]
[TBD: Decision pending - who needs to decide]

Before Writing Any Technical Detail

1. **Service names** - search codebase, verify service exists 2. **API endpoints** - read actual proto files or route definitions 3. **Database tables** - find actual schema/migrations 4. **Data models** - read actual model/entity files 5. **Business logic** - read actual implementation code 6. **Dependencies** - check package.json, build.gradle, requirements.txt

---

Workflow

Phase 1: Gather Context

Before drafting, collect and verify information from all available sources.

**Step 1: Fetch External Context via MCP**

Jira/Linear ticket (if provided):

• Fetch full ticket details: description, acceptance criteria, linked issues
• Walk the parent chain (epic, initiative) for broader context
• Check remote links for Confluence, Figma, Notion references

Confluence/Notion docs (if referenced):

• Fetch related docs, DACIs, existing tech notes
• Search for related TDDs in the same area

Figma designs (if linked):

• Get design context, component structure
• Capture screenshots for visual reference

**Step 2: Explore Existing UI (if modifying an existing system)**

If the feature modifies an existing interface, explore the current state:

• Navigate to the relevant pages
• Document current UI layout, components, user flows
• Note current limitations and UX issues
• Identify patterns to maintain or improve

**Step 3: Analyze Codebase (required)**

Read actual code before writing technical details:

• Search for affected services, read entry points
• Find existing data models, database migrations
• Check proto files for message definitions
• Understand current architecture: API routes, service communication
• Review related code for patterns
• Find similar features for reference

**Step 4: Mark All Unknowns**

After gathering, explicitly list what could NOT be verified:

• Missing schema information
• Unclear service boundaries
• Unconfirmed business logic
• Pending decisions

Phase 2: Draft Structure

The template below is a **coverage checklist for the author, not a layout for the reader**. It lists what a good TDD considers. It does not mean each heading gets three bullets and a code block. As you fill it, follow one rule above all others: **write each section as prose a colleague could read aloud.** Reach for a list or table only when the content is genuinely parallel and order-independent, a roster of endpoints, a t-shirt-size scale, a test matrix. The moment a "list" has bullets that depend on each other (this happens, *then* that, *because* of the other), it's a paragraph wearing a list costume. Write the paragraph.

Drop sections that don't apply rather than filling them with "N/A" noise. Mark ANY unverified information with the markers above.

# TDD: [Initiative Title]

**Author:** [Name]
**Team:** [Team/Squad Name]
**Status:** IN REVIEW | GO | NO GO

**Links:**
- Ticket: [link]
- Designs: [link]
- Docs: [link]

---

## Introduction

### Context
[1-2 paragraphs: What problem are we solving? Business-oriented terms.]

### Problem Statement (Current State)
[Current limitations, pain points, gaps.]

### Current Flow (if modifying existing system)
[Document the existing UI and user flow.]

### Proposed Solution
[2-3 sentences: How do you plan on solving it?]

### Long Term Vision
[How does this bring us closer to the team's long-term goals?]

---

## Decision Record

- **Driver:** [Author]
- **Approver:** [EM or senior IC with domain expertise]
- **Contributors:** [Your team, affected teams]
- **Informed:** [Engineering, PM, relevant stakeholders]

---

## Phase 1

### LOE (T-Shirt Size)

| Size | Time |
|------|------|
| XS | 1-2 days |
| S | 1 week |
| M | 2 weeks |
| L | 4 weeks |
| XL | 4+ weeks |

**This phase:** [SIZE]

### External dependencies & impact

[Prose. Who else is affected and how? Name the teams that depend on this or whose
systems you touch, the vendors (with co