Docs Retrieval

Red Flags - STOP and Reconsider

If you're about to:

• Load full-context.md for a simple question
• Web search without checking local docs first
• Let sub-agents navigate from scratch instead of passing context
• Load all libraries "just in case"

STOP -> Use targeted retrieval patterns below -> Then proceed

Workflow

1. CHECKPOINT: Have you identified what libraries you need?
2. Check ai-docs/libraries/_index.toon for available docs
3. Navigate to specific library _index.toon
4. Identify relevant pages from index
5. Load only the page summaries you need
6. CHECKPOINT: Are you within token budget?

Cookbook

Direct Navigation

• IF: You know the library and topic
• THEN: Read cookbook/direct-navigation.md
• RESULT: Fastest path to specific information

Keyword Search

• IF: Uncertain which library has what you need
• THEN: Read cookbook/keyword-search.md
• RESULT: Find relevant docs by matching keywords

Multi-Library Gathering

• IF: Task involves multiple libraries
• THEN: Read cookbook/multi-library.md
• RESULT: Consolidated context from multiple sources

Full Context Loading

• IF: Need comprehensive understanding (migrations, tutorials)
• THEN: Read cookbook/full-context.md
• WARNING: High token cost (5,000-15,000 tokens)

When to Use This Skill

• Before implementing features involving external libraries
• When debugging errors from external dependencies
• When spawning sub-agents that need library context
• When uncertain about API syntax or behavior

Retrieval Patterns

Pattern 1: Direct Navigation (Know What You Need)

When you know the library and topic:

1. @ai-docs/libraries/{library}/_index.toon
   -> Read overview and common_tasks

2. Find matching task or section
   -> Note the page path

3. @ai-docs/libraries/{library}/{section}/pages/{page}.toon
   -> Get detailed summary with gotchas and patterns

Example: Need BAML retry configuration

1. @ai-docs/libraries/baml/_index.toon
   -> common_tasks: "Handle errors gracefully" -> guide/error-handling

2. @ai-docs/libraries/baml/guide/pages/error-handling.toon
   -> RetryPolicy syntax, gotchas about timeouts

Pattern 2: Keyword Search (Uncertain What Exists)

When you're not sure which library or page:

1. @ai-docs/libraries/_index.toon
   -> Scan library descriptions and keywords

2. Match your need against keywords
   -> Identify candidate libraries

3. For each candidate:
   -> @ai-docs/libraries/{lib}/_index.toon
   -> Check if relevant content exists

4. Load specific pages from best match

Example: Need "structured output parsing"

1. @ai-docs/libraries/_index.toon
   -> BAML: "Structured LLM outputs with type safety" [match]
   -> MCP: "Tool integration protocol" [no match]

2. @ai-docs/libraries/baml/_index.toon
   -> Confirms: type system, parsing, validation

3. Load relevant BAML pages

Pattern 3: Multi-Library Gathering (Complex Tasks)

When task involves multiple libraries:

1. List all libraries involved in task

2. For each library:
   -> Load _index.toon
   -> Identify relevant pages
   -> Load page summaries

3. Consolidate into single context block

4. OR: Spawn docs-context-gatherer agent

Pattern 4: Full Context (Deep Work)

When you need comprehensive understanding:

@ai-docs/libraries/{library}/full-context.md

Use sparingly - this loads everything (~5,000-15,000 tokens)

Appropriate for:

• Major migrations
• Writing tutorials
• Architectural decisions
• First-time deep learning

Context Consolidation Format

When gathering context from multiple pages, consolidate as:

## Documentation Context

### {Library}: {Topic}
**Purpose**: {1-2 sentence purpose}
**Key Points**:
- {concept 1}
- {concept 2}
**Gotchas**:
- {warning 1}
- {warning 2}
**Pattern**:
```{language}
{minimal code example}

{Library}: {Another Topic}

...

Sources: {list of page paths loaded} Tokens: ~{estimate}

## Budget Management

### Token Estimates by File Type

| File Type | Typical Size |
|-----------|--------------|
| `_index.toon` (category) | 100-150 tokens |
| `_index.toon` (library) | 150-250 tokens |
| `_index.toon` (section) | 100-200 tokens |
| `pages/*.toon` | 250-450 tokens |
| `full-context.md` | 5,000-15,000 tokens |

### Budget Guidelines

| Task Type | Target Budget | Loading Strategy |
|-----------|---------------|------------------|
| Quick fix | 300-500 | 1 page summary |
| Single feature | 800-1,200 | 2-3 page summaries |
| Integration | 1,500-2,500 | Library index + 4-6 pages |
| Multi-library | 2,000-4,000 | Multiple library indexes + key pages |
| Full context | 5,000+ | full-context.md |

### Efficiency Tips

1. **Index files are cheap navigation** - Read them freely
2. **Page summaries are high-signal** - Designed for this purpose
3. **Gotchas prevent expensive mistakes** - Always worth loading
4. **Code patterns are copy-paste ready** - High value per token
5. **full-context.md is last resort** - Use targeted loading first

## Common Retrieval Scenarios

### Scenario: Implementing a Feature

1. Identify: What libraries does this feature use?
2. Navigate: Find relevant pages in each library
3. Load: Page summaries for implementation guidance
4. Note: Gotchas before writing code
5. Proceed: Implement with context loaded

### Scenario: Debugging an Error

1. Identify: Which library produced the error?
2. Search: Error-related pages in that library
3. Load: Error handling and troubleshooting pages
4. Check: Known gotchas that might explain the issue
5. Proceed: Debug with context

### Scenario: Spawning Sub-Agent

1. Analyze: What docs will sub-agent need?
2. Gather: Load relevant pages NOW
3. Consolidate: Format as context block
4. Include: Add to sub-agent spawn prompt
5. Spawn: Sub-agent has pre-loaded context

### Scenario: Uncertain Which Library

1. Start: @ai-docs/libraries/_index.toon
2. Scan: Library descriptions and keywords
3. Match: Find libraries relevant to your need
4. Explore: Check promising library indexes
5. Load: Pages from best matching library

### Scenario: AI Tool Documentation

When you need information about AI tools (Claude Code, BAML, MCP, TOON, etc.):

1. Check local ai-docs FIRST: @ai-docs/libraries/claude-code/_index.toon @ai-docs/libraries/baml/_index.toon @ai-docs/libraries/toon/_index.toon

2. Navigate using same patterns as any library: -> Find section in _index.toon -> Load relevant page summaries -> Use full-context.md for comprehensive needs

3. Fall back to web search/fetch when:

   • Local docs don't cover the specific topic
   • Need time-sensitive info (release dates, latest versions)
   • Local docs are insufficient after checking
   • User explicitly requests current web information

**Why local first:**
- Faster (no network round-trip)
- Curated context (TOON format optimized for LLMs)
- Gotchas pre-extracted
- Token-efficient vs. full web pages

**When to web search:**
- Topic not found after checking local index
- Need current/live information
- User explicitly asks for latest from web

## Anti-Patterns

### Don't: Load full-context.md for Simple Questions

**Bad**: Load 15K tokens to answer "what's the retry syntax?"
**Good**: Navigate to specific page, load ~400 tokens

### Don't: Skip Documentation

**Bad**: "I probably remember how this works..."
**Good**: Take 30 seconds to load relevant page

### Don't: Re-Navigate in Sub-Agents

**Bad**: Each sub-agent navigates from scratch
**Good**: Parent loads context, passes to sub-agents

### Don't: Load Everything "Just in Case"

**Bad**: Load all libraries mentioned anywhere
**Good**: Load specific pages for specific needs

## Integration with Protocol

This skill implements the retrieval portions of:
`.claude/ai-dev-kit/protocols/docs-management.md`

Always follow the protocol's decision flow:
1. Task Analysis -> Identify libraries
2. Documentation Check -> Verify docs exist
3. Context Loading -> Use this skill's patterns
4. Execute with Context -> Proceed with task