draft-docs skill

Draft Docs

Generate Tutorial, How-To, Reference, or Explanation documentation drafts to docs/drafts/ for review before publishing. These are the four Diataxis types — see 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
"how to", "guide", "steps", "configure", "set up"	How-To	howto-docs
"API", "reference", "parameters", "function", "endpoint"	Reference	reference-docs
"why", "how does it work", "concept", "background", "rationale", "design decision", "architecture", "trade-offs"	Explanation	explanation-docs

These four types are the quadrants of the Diátaxis 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. 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 - Core writing principles
2. Detected type skill:
   • tutorial-docs for Tutorial
   • howto-docs for How-To
   • reference-docs for Reference
   • explanation-docs 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 file (see Hard gates → Write gate: confirm file on disk before the next step)

4. Report to user:

   ## Draft Created
   
   **File:** `docs/drafts/{slug}.md`
   **Type:** Tutorial | How-To | Reference | Explanation
   **Based on:** [list of analyzed symbols/files]
   
   ### Next Steps
   
   1. Review the draft for accuracy
   2. Add any missing context or examples
   3. When ready, publish by invoking the **draft-docs** skill with `--publish docs/drafts/{slug}.md`
   

Step 6: End-of-Run Verification

Verify draft generation completed successfully:

# Confirm draft file exists
ls -la docs/drafts/{slug}.md

# Validate frontmatter (YAML header)
head -10 docs/drafts/{slug}.md | grep -E "^---$|^title:|^description:"

# Check markdown syntax (if markdownlint available)
markdownlint docs/drafts/{slug}.md 2>/dev/null || echo "markdownlint not available"

Verification Checklist:

• Draft file created at docs/drafts/{slug}.md
• Frontmatter includes title and description
• Content type matches detected type (Tutorial, How-To, Reference, or Explanation)
• Code examples are complete and runnable (Tutorial/How-To/Reference); concepts grounded in real design decisions (Explanation)
• Tutorial drafts give a single path with observable "You should see…" outcomes at each step
• All analyzed symbols referenced in draft

If any verification fails, report the specific issue and offer to regenerate.

Mode 2: Publish Draft

Invoke the draft-docs skill with the --publish flag, e.g. draft-docs --publish docs/drafts/websocket-api.md.

Step 1: Read Draft

Read the draft file and extract:

• Title
• Content type (from frontmatter or structure)

Step 2: Determine Destination

Ask user which section:

Where should this document go?

1. **Tutorials** → `docs/tutorials/{slug}.md`
2. **API Reference** → `docs/api/{slug}.md`
3. **Guides** → `docs/guides/{slug}.md`
4. **How-To** → `docs/how-to/{slug}.md`
5. **Concepts / Explanation** → `docs/concepts/{slug}.md`
6. **Other** → Specify path

Step 3: Move File

mv docs/drafts/{slug}.md {destination}/{slug}.md

Step 4: Update Navigation

Check for docs/navigation.json and update navigation:

1. Read current navigation.json
2. Find appropriate navigation group
3. Add new page entry
4. Write updated navigation.json

Example update:

{
  "navigation": [
    {
      "group": "API Reference",
      "pages": [
        "api/existing-page",
        "api/websocket-api"
      ]
    }
  ]
}

Step 5: Report

## Published

**From:** `docs/drafts/{slug}.md`
**To:** `{destination}/{slug}.md`
**Navigation:** Updated `docs/navigation.json`

The document is now live in your docs.

Step 6: End-of-Run Verification

Verify publish completed successfully:

# Confirm file moved to destination
ls -la {destination}/{slug}.md

# Confirm draft removed
ls docs/drafts/{slug}.md 2>/dev/null && echo "WARNING: Draft still exists" || echo "Draft cleaned up"

# Verify navigation updated
grep -q "{slug}" docs/navigation.json && echo "Navigation includes new page" || echo "WARNING: Navigation may need manual update"

# Check markdown syntax at final location
markdownlint {destination}/{slug}.md 2>/dev/null || echo "markdownlint not available"

Verification Checklist:

• Document moved to {destination}/{slug}.md
• Draft removed from docs/drafts/
• Navigation file updated with new page entry
• No broken links in navigation structure
• Document accessible at expected URL path

If any verification fails, report the specific issue and offer remediation steps.

Content Type Detection

Tutorial Indicators

• Prompt mentions: tutorial, learn, getting started, first, onboarding, introduction, "build a/your"
• Target is a beginner's first successful experience with the product
• User wants a guided, learn-by-doing lesson, not a task or a lookup

Reference Indicators

• Prompt mentions: API, endpoint, function, method, class, type, parameters, returns
• Target is a specific symbol or set of symbols
• User wants technical specification

How-To Indicators

• Prompt mentions: how to, guide, steps, configure, set up, integrate
• Target is a task or workflow
• User wants procedural instructions

Explanation Indicators

• Prompt mentions: why, how it works, concept, background, rationale, design decision, architecture, trade-offs
• Target is a concept or system the reader wants to understand, not operate
• User wants context and reasoning to read away from the keyboard, not steps to follow

Rules

• Always load docs-style skill for every draft
• Generate to docs/drafts/ - never directly to final location
• Include frontmatter with title and description
• Use realistic examples from actual codebase
• Reference analyzed symbols in draft metadata
• Preserve existing navigation structure when publishing
• Ask before overwriting existing files

Hard gates (sequenced)

Do not skip ahead: each Pass must be true before the next step. Use commands or explicit artifacts—not internal assurance.

Generate draft (Mode 1)

1. Context gate — Pass: Step 0 commands ran (or equivalent) and you recorded at least one concrete outcome: e.g. docs/ listing snippet, or explicit note that docs/ is missing and will be created.
2. Type gate — Pass: Tutorial vs How-To vs Reference vs Explanation is decided using the keyword table and the two compass questions or the user’s explicit answer (quote or paraphrase with “user chose …”). Do not start Step 3: Analyze Code until this is locked.
3. Skills gate — Pass: Before analysis, both are in play: docs-style and the type skill (tutorial-docs, howto-docs, reference-docs, or explanation-docs). In your run, name the two skills loaded (paths)—not “I reviewed writing guidelines.”
4. Write gate — Pass: After writing the draft, test -f docs/drafts/{slug}.md succeeds (or ls shows the file). Only then emit the Draft Created block.

Publish draft (Mode 2)

1. Destination gate — Pass: User chose a destination (from the menu or a specific path). Resolve {destination} to a full path; Pass when the parent directory exists (test -d "$(dirname "$path")" or project-appropriate check) and you are not overwriting an existing file without explicit user approval.
2. Move gate — Pass: After mv, the file exists at {destination}/{slug}.md (test -f) and navigation updates (if applicable) are applied before claiming Published.