/draft-docs

name: draft-docs
description: Generate first-draft technical documentation from code analysis
disable-model-invocation: true

Draft Docs

Generate Tutorial, How-To, Reference, or Explanation documentation drafts to `docs/drafts/` for review before publishing. These are the four [Diataxis](https://diataxis.fr/) types — see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md) for the full type-selection procedure.

Arguments

• **Topic prompt:** Description of what to document (e.g., "Document the WebSocket API")
• **--publish [file]:** Move reviewed draft to final location and update navigation

Mode 1: Generate Draft

Invoke the **draft-docs** skill with a topic prompt, e.g. `draft-docs "Document the authentication middleware"`.

Step 0: Gather Context

Before parsing input, gather project context:

# Check for existing docs structure
ls -la docs/ 2>/dev/null || echo "No docs/ directory found"

# Identify documentation framework
ls docs/navigation.json docs/mint.json docs/docusaurus.config.js docs/mkdocs.yml 2>/dev/null | head -1

# Check for existing drafts
ls docs/drafts/*.md 2>/dev/null || echo "No existing drafts"

# Get recent code changes for context
git diff --name-only $(git merge-base HEAD main)..HEAD 2>/dev/null | head -20

**Capture:**

• Docs structure: `docs/` subdirectories present
• Navigation system: `navigation.json`, `mint.json`, or other config
• Tech stack hints: from file extensions and imports in changed files
• Existing drafts: to avoid duplicates

Step 1: Parse Input

Extract from the prompt:

1. **Topic:** What to document (e.g., "authentication middleware") 2. **Content type:** Detect from keywords:

| Keywords | Type | Skill | |----------|------|-------| | "tutorial", "learn", "getting started", "first", "onboarding", "introduction", "build a/your" | Tutorial | [tutorial-docs](../tutorial-docs/SKILL.md) | | "how to", "guide", "steps", "configure", "set up" | How-To | [howto-docs](../howto-docs/SKILL.md) | | "API", "reference", "parameters", "function", "endpoint" | Reference | [reference-docs](../reference-docs/SKILL.md) | | "why", "how does it work", "concept", "background", "rationale", "design decision", "architecture", "trade-offs" | Explanation | [explanation-docs](../explanation-docs/SKILL.md) |

These four types are the quadrants of the [Diátaxis](https://diataxis.fr/) framework — Tutorial (learning), How-To (task), Reference (information), and Explanation (understanding). Decide with the two compass questions — *action or cognition? acquisition or application?* — detailed in [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md). Two distinctions resolve most ambiguity:

• **Tutorial vs. How-To** both give action steps, but a Tutorial teaches a beginner through a guaranteed-to-succeed lesson (study), while a How-To directs a competent user toward a real goal (work). If the reader is learning the product for the first time, it's a Tutorial; if they already know it and want to get a task done, it's a How-To.
• **Reference vs. Explanation** both serve theoretical knowledge, but Reference *states* neutral facts to consult at the keyboard, while Explanation *discusses* reasoning and context to read away from it. If the request wants opinions, history, or trade-offs, it's Explanation; if it wants an authoritative spec, it's Reference.

If ambiguous, ask: "Should this be a Tutorial (learning by doing), a How-To guide (task completion), a Reference doc (technical lookup), or an Explanation (understanding the why behind a concept)?"

Step 2: Load Skills

Always load both:

1. [docs-style](../docs-style/SKILL.md) - Core writing principles 2. Detected type skill:

• [tutorial-docs](../tutorial-docs/SKILL.md) for Tutorial
• [howto-docs](../howto-docs/SKILL.md) for How-To
• [reference-docs](../reference-docs/SKILL.md) for Reference
• [explanation-docs](../explanation-docs/SKILL.md) for Explanation

Step 3: Analyze Code

Search the codebase for relevant code:

1. **Symbol search:** Find functions, classes, types matching the topic 2. **File search:** Locate related files by name patterns 3. **Reference search:** Find usage examples

Gather:

• Function/method signatures
• Type definitions
• Existing comments/docstrings
• Usage patterns in tests or examples

Step 4: Generate Draft

Apply the loaded skills to generate documentation:

**For Tutorial docs:**

• Follow `tutorial-docs` template structure
• Title names what the reader will build ("Build your first X"), not what they'll learn
• Use first-person plural — "In this tutorial, we will…" — to keep the teacher/learner narrative
• Give one clear path with no choices or alternatives
• After every step, state what the reader should see ("You should see…")
• Ruthlessly minimize explanation; link out to Explanation docs for the "why"

**For Reference docs:**

• Follow `reference-docs` template structure
• Document all parameters with types
• Include complete, runnable examples from actual code
• Add Related section linking to connected symbols

**For How-To docs:**

• Follow `howto-docs` template structure
• Start title with "How to"
• List concrete prerequisites
• Break into single-action steps
• Include verification section

**For Explanation docs:**

• Follow `explanation-docs` template structure
• Frame the title around understanding a concept ("Understanding X"), not a task
• Open by stating what the reader will understand after reading
• Explain the *why* behind design decisions, not just what exists
• Discuss trade-offs honestly and acknowledge alternatives that were considered
• Write flowing prose for reading away from the keyboard — no steps to follow

Step 5: Write Draft

1. **Create output path:**

• `docs/drafts/{slug}.md`
• Slug from topic: "WebSocket API" → `websocket-api.md`

2. **Ensure directory exists:**

   mkdir -p docs/drafts

3. **Write the draft fi