/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 1.5: Set the bet

Before drafting, run `/flagrare:measure-impact` with `before <ticket, doc or initiative link> full called by /flagrare:tdd-writer`. Use what it returns in two places: the **For product** paragraph at the top of the Introduction (the bet, the number it should move with today's value and its source, how sure we are, what is out of scope), and the Analytics or Observability section (how the change will be tracked). When it reports a baseline as unknown, keep that visible in the doc ("baseline unknown: <how to get it>") instead of inventing a number.

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

### For product
[3 to 5 plain sentences a product manager can read without the rest of the doc: what changes for users, the bet from /flagrare:measure-impact (the number it should move, today's value and its source, how sure we are), and what is out of scope.]

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

### Problem Statement (Current S