draft-docs

# 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:

```bash
# 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:**
   ```bash
   mkdir -p docs/drafts
   ```

3. **Write the draft file** (see **Hard gates** → Write gate: confirm file on disk before the next step)

4. **Report to user:**
   ```markdown
   ## Draft