Draft Docs

Generate first-draft technical documentation from code analysis

Generate Reference or How-To documentation drafts to docs/drafts/ for review before publishing.

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
"how to", "guide", "steps", "configure", "set up"	How-To	howto-docs
"API", "reference", "parameters", "function", "endpoint"	Reference	reference-docs

If ambiguous, ask: "Should this be a Reference doc (technical lookup) or How-To guide (task completion)?"

Step 2: Load Skills

Always load both:

1. docs-style - Core writing principles
2. Detected type skill:
   • reference-docs for Reference
   • howto-docs for How-To

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

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:** Reference | How-To
   **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 (Reference or How-To)
• Code examples are complete and runnable
• 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. **API Reference** → `docs/api/{slug}.md`
2. **Guides** → `docs/guides/{slug}.md`
3. **How-To** → `docs/how-to/{slug}.md`
4. **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

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

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: Reference vs How-To is decided using the keyword table 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 (reference-docs or howto-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.