---
name: design-doc-writer
description: A specialized skill that teaches the agent to write extremely detailed technical design docs, architecture documents, or technical specifications. Use this skill whenever you need to produce a technical design document.
---

# Design Doc Writer

## Overview
This skill instructs the agent to write highly detailed, heavily
explained technical design documents. The resulting documentation must
strictly adhere to specific naming conventions, file placements, and
possess a comprehensive depth of detail ensuring that an inexperienced
intern can follow and implement the designed system.

## File Placement and Naming Conventions
Whenever you generate a design document, follow these exact rules:
- **Directory**: The document MUST be created inside the `designs/`
  directory. If the directory does not exist, create it.
- **Naming Pattern**: `design-<index>-<topic>.md`
  - `<index>`: An integer starting from `0`. Check the `designs/`
    directory to see if any `design-<index>-<topic>.md` files already
    exist. If so, find the highest index and use the next integer. If
    none exist, start with `0`.
  - `<topic>`: A **single word** that describes what the document is
    about (e.g., `design-0-database.md`, `design-1-auth.md`,
    `design-2-api.md`).

## Detail and Depth Requirements
The core mandate for these design docs is **extreme detail**. You must
ensure the following:
- **Comprehensive Explanations**: Everything in the document must have
  an explanation.
- **Recursive Depth**: Explanations must themselves have explanations.
  Every concept, architecture choice, or piece of logic must be broken
  down to its fundamentals. Do not gloss over details or assume prior
  knowledge.
- **Audience Level**: The doc must be written so that an
  **inexperienced intern** could read it, follow the instructions, and
  successfully implement the entire system without having to ask
  questions.
- **Step-by-Step Guidance**: When outlining algorithms, logic, or
  system flows, provide a granular, step-by-step breakdown.
- **Data Structures & APIs**: Explicitly detail data models, payload
  structures, API endpoints, error handling, edge cases, and testing
  strategies.

## External References
You MUST use markdown links to external references, official
documentation, tutorials, or relevant RFCs whenever appropriate to
back up your technical choices and provide further reading for the
intern.

## Execution Workflow
When executing a request to create a design doc using this skill,
perform the following steps:
1. **Analyze**: Understand the technical topic requested by the user.
2. **Determine File Name**: List the `designs/` directory to determine
   the correct `<index>`, and choose an appropriate single-word
   `<topic>`.
3. **Draft the Document**: Produce the detailed markdown content
   adhering strictly to the depth and formatting requirements.
4. **Save**: Save the finalized content to the path
   `designs/design-<index>-<topic>.md`.