Draft Docs

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

/beagle-docs: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:

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. beagle-docs:docs-style - Core writing principles
2. Detected type skill:
   • beagle-docs:reference-docs for Reference
   • beagle-docs: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