Blueprint Curate Docs

/blueprint:curate-docs

Curate library or project documentation into ai_docs entries optimized for AI agents - concise, actionable, gotcha-aware context that fits in PRPs.

Usage: /blueprint:curate-docs [library-name] or /blueprint:curate-docs project:[pattern-name]

When to Use This Skill

Context

• ai_docs directory: !find docs/blueprint -maxdepth 1 -name 'ai_docs' -type d
• Existing library docs: !find docs/blueprint/ai_docs/libraries -name "*.md" -type f
• Existing project patterns: !find docs/blueprint/ai_docs/project -name "*.md" -type f
• Library in dependencies: !find . -maxdepth 1 \( -name package.json -o -name pyproject.toml -o -name requirements.txt \) -exec grep -m1 "^$1[\":@=]" {} +

Parameters

Parse $ARGUMENTS:

• library-name: Name of library to document (e.g., redis, pydantic)
• Location: docs/blueprint/ai_docs/libraries/[library-name].md
• OR project:[pattern-name] for project patterns
• Location: docs/blueprint/ai_docs/project/[pattern-name].md

Execution

Execute complete documentation curation workflow:

Step 1: Determine target and check existing docs

1. Parse argument to determine if library or project pattern 2. Check if ai_docs entry already exists 3. If exists → Ask: Update or create new version? 4. Check project dependencies for library version

Step 2: Research and gather documentation

For libraries:

• Find official documentation URL
• Search for specific sections relevant to project use cases
• Find known issues and gotchas (WebSearch: "{library} common issues", "{library} gotchas")
• Extract key sections with WebFetch

For project patterns:

• Search codebase for pattern implementations: grep -r "{pattern}" src/
• Identify where and how it's used
• Document conventions and variations
• Extract real code examples from project

Step 3: Extract key information

1. Use cases: How/why this library/pattern is used in project 2. Common operations: Most frequent uses 3. Patterns we use: Project-specific implementations (with file references) 4. Configuration: How it's configured in this project 5. Gotchas: Version-specific behaviors, common mistakes, performance pitfalls, security considerations

Sources for gotchas: GitHub issues, Stack Overflow, team experience, official docs warnings.

Step 4: Create ai_docs entry

Generate file at appropriate location (see REFERENCE.md):

• docs/blueprint/ai_docs/libraries/[library-name].md OR
• docs/blueprint/ai_docs/project/[pattern-name].md

Include all sections from template: Quick Reference, Patterns We Use, Configuration, Gotchas, Testing, Examples.

Keep under 200 lines total.

Step 5: Add code examples

Include copy-paste-ready code snippets from:

• Project codebase (reference actual files and line numbers)
• Official documentation examples
• Stack Overflow solutions
• Personal implementation experience

Step 6: Update task registry

Update the task registry entry in docs/blueprint/manifest.json:

jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --argjson processed "${ITEMS_PROCESSED:-0}" \
  --argjson created "${ITEMS_CREATED:-0}" \
  '.task_registry["curate-docs"].last_completed_at = $now |
   .task_registry["curate-docs"].last_result = "success" |
   .task_registry["curate-docs"].stats.runs_total = ((.task_registry["curate-docs"].stats.runs_total // 0) + 1) |
   .task_registry["curate-docs"].stats.items_processed = $processed |
   .task_registry["curate-docs"].stats.items_created = $created' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

Step 7: Validate and save

1. Verify entry is < 200 lines 2. Verify all code examples are accurate 3. Verify gotchas include solutions 4. Save file 5. Report completion

Agentic Optimizations

---

For ai_docs template, section guidelines, and example entries, see REFERENCE.md.

blueprint-curate-docs REFERENCE

ai_docs Template

# [Library/Pattern Name]

**Version:** X.Y.Z
**Last Updated:** YYYY-MM-DD
**Use Case:** [Why we use this in this project]

## Quick Reference

### [Common Operation 1]
\`\`\`language
# Code snippet that can be directly copied
\`\`\`

## Patterns We Use

### [Pattern Name]
[When to use this pattern]

\`\`\`language
# Full example as used in this project
# Reference: src/path/file.ts:15-25
\`\`\`

## Configuration

\`\`\`
VAR_NAME=value
\`\`\`

## Gotchas

### Gotcha 1: [Title]
**Issue:** [What can go wrong]
**Solution:**
\`\`\`language
# Correct approach
\`\`\`

## Testing

### How to Mock
\`\`\`language
# Mocking pattern for tests
\`\`\`

## References
- [Official docs](https://...)
- [Related code](src/path/file.ts)

Section Guidelines

Line Count Target

< 200 lines total. Concise and actionable, not comprehensive documentation.

Code Example Format

Include file/line references:

// Reference: src/auth/handlers.ts:42-55
function login(req, res) {
  // Implementation
}

Gotcha Format

Always include solution:

### Gotcha: Connection pool exhaustion
**Issue:** Pool defaults to 10, causes timeouts under load
**Solution:** Set pool size to CPU count × 4