Draft Docs

Generate Reference or How-To documentation drafts to

docs/drafts/

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:

howto-docs

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

3. Write the draft file

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

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

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

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