# Scaling Strategies for Documentation Plugins

This guide explains how to manage token budgets and scale documentation plugins from hundreds to thousands of pages without context explosion.

## The Token Problem

**Context window constraints:**
- LLMs have finite context windows (e.g., 200k tokens)
- Skills consume context when loaded
- Large documentation = massive token usage
- Multiple skills loaded simultaneously = compounding problem

**Example math:**
- 1000 pages of docs at ~500 tokens/page = 500k tokens
- Even with summarization: ~50k-100k tokens minimum
- Cannot load alongside other skills or conversation history
- Result: Unusable at scale

## The Solution: Token Budgeting

**Core principle:** Keep each skill under 500 lines (~3-5k tokens) through:
1. Separation of docs from patterns
2. Grep-driven discovery (don't load docs)
3. Progressive disclosure (load only what's needed)
4. Strategic cross-linking (share instead of duplicate)

## Budgeting Framework

### Skill Budget Allocation

| Skill Type | Target Lines | Token Budget | Content Strategy |
|------------|--------------|--------------|------------------|
| Docs Skill | 300-400 | ~2-3k | Grep patterns + structure overview |
| Application Skill | 300-400 | ~2-3k | Focused patterns + cross-links |
| Advanced Skill | 400-500 | ~3-4k | Deep patterns + optimization |
| Integration Skill | 300-400 | ~2-3k | Integration patterns + cross-links |

**Total for 4-skill plugin:** ~1500-1700 lines (~10-15k tokens)

Compare to monolithic approach:
- Single massive skill: 3000+ lines (~30k+ tokens)
- Cannot compose with other skills
- Poor user experience (hard to navigate)

### Content Distribution

**Docs Skill (300-400 lines):**
- Frontmatter: ~10 lines
- Introduction: ~20 lines
- Quick reference (grep patterns): ~50 lines
- Documentation structure overview: ~50 lines
- Cross-references to application skills: ~50 lines
- Common lookup patterns: ~100 lines
- Troubleshooting reference: ~30 lines
- Maintenance notes: ~20 lines

**Application Skill (300-400 lines):**
- Frontmatter: ~10 lines
- Introduction + when to use: ~30 lines
- Quick pattern reference: ~20 lines
- Basic patterns (2-3): ~100 lines
- Advanced pattern (1): ~50 lines
- Cross-reference guide: ~50 lines
- Common pitfalls: ~40 lines
- Production patterns reference: ~30 lines
- Next steps: ~20 lines

## Scaling Techniques

### 1. Horizontal Scaling (Add More Skills)

**When to split:**
- Skill exceeds 500 lines
- Distinct user workflows emerge
- Different expertise levels needed
- Integration patterns grow large

**How to split:**

```
Before (monolithic):
tech-mastery/
└── tech-all/
    └── SKILL.md (1500 lines - everything)

After (scaled):
tech-mastery/
├── tech-docs/ (400 lines - passive reference)
├── tech-basics/ (350 lines - getting started)
├── tech-patterns/ (400 lines - common workflows)
├── tech-advanced/ (450 lines - optimization)
└── tech-integration/ (350 lines - third-party tools)
```

**Result:**
- Total: 1950 lines across 5 skills
- Each skill: 350-450 lines (composable)
- Users load only what they need

### 2. Vertical Scaling (Compress Content)

**Techniques:**

**A. Progressive Disclosure**

```markdown
<!-- Instead of this (200 lines): -->
## Error Handling

Here's every possible error pattern... [200 lines of examples]

<!-- Do this (30 lines): -->
## Error Handling → tech-docs

For complete error reference:
\```bash
rg "Error:\\|Exception:" ../tech-docs/references/guides/ -i -A3
\```

**Common patterns:**
- Network errors: ECONNREFUSED, ETIMEDOUT
- Auth errors: 401, 403
- Database errors: See tech-advanced for retry patterns
```

**Savings:** 170 lines (~1500 tokens)

**B. Reference, Don't Duplicate**

```markdown
<!-- Instead of this (100 lines): -->
## SQL Function Reference

Here are all 50 SQL functions with examples... [100 lines]

<!-- Do this (10 lines): -->
## SQL Function Reference → tech-docs

\```bash
rg "JSON_VALUE\\|ARRAY_AGG" ../tech-docs/references/api-reference/
\```
```

**Savings:** 90 lines (~800 tokens)

**C. Example Compression**

```markdown
<!-- Instead of this (50 lines): -->
// Example 1: Basic query
const example1 = ...

// Example 2: With parameters
const example2 = ...

// Example 3: With joins
const example3 = ...

<!-- Do this (15 lines): -->
**Pattern:**
\```typescript
const query = (client: Client, params: Params) =>
  Effect.gen(function* () {
    return yield* client.query(params)
  })
\```

**Variations:** See samples: `rg "client.query" ../tech-docs/references/samples/ -A10`
```

**Savings:** 35 lines (~300 tokens)

### 3. Documentation Organization

**Flat vs Hierarchical:**

**Flat (better for grep):**
```
references/
├── api-function-1.md
├── api-function-2.md
├── guide-getting-started.md
├── guide-best-practices.md
└── sample-basic-usage.md
```

**Hierarchical (harder to search):**
```
references/
├── api/
│   ├── functions/
│   │   ├── function-1.md
│   │   └── function-2.md
├── guides/
│   ├── getting-started/
│   │   └── intro.md
```

**Recommendation:** Use shallow hierarchy (2 levels max):

```
references/
├── guides/
│   ├── getting-started.md
│   └── best-practices.md
├── api-reference/
│   ├── functions.md
│   └── classes.md
└── samples/
    ├── basic-usage.md
    └── advanced-patterns.md
```

**Why:** Easier grep patterns, flatter paths, better discoverability.

### 4. Smart Grep Pattern Design

**Token-efficient patterns:**

```bash
# ❌ EXPENSIVE - loads 500 files into context
find references/ -name "*.md" | xargs cat | grep "pattern"

# ✅ CHEAP - just file paths (20 tokens vs 50k)
rg "pattern" references/ -l | head -5

# ✅ EFFICIENT - targeted context (500 tokens vs 5k)
rg "pattern" references/guides/getting-started.md -A5
```

**Budget impact:**
- File listing: ~1-2 tokens per file
- With context (-A5): ~50-100 tokens per match
- Full file read: ~500-1000 tokens

**Rule:** Default to `-l` (files only), add context only when needed.

### 5. Skill Composition Strategies

**Composition A: Technology Stack**

```
react-mastery/
├── react-docs/       (passive reference)
├── react-hooks/      (useState, useEffect, etc.)
├── react-router/     (routing patterns)
└── react-testing/    (testing patterns)
```

**Total budget:** 4 skills × 350 lines = 1400 lines

**Composition B: Expertise Levels**

```
postgres-mastery/
├── postgres-docs/    (passive reference)
├── postgres-basics/  (CRUD, simple queries)
├── postgres-advanced/(optimization, indexing)
└── postgres-admin/   (backups, replication)
```

**Total budget:** 4 skills × 400 lines = 1600 lines

**Composition C: Workflow-Oriented**

```
k8s-mastery/
├── k8s-docs/         (passive reference)
├── k8s-deploy/       (deployment workflows)
├── k8s-monitor/      (monitoring patterns)
└── k8s-debug/        (troubleshooting)
```

**Total budget:** 4 skills × 375 lines = 1500 lines

**Choose based on:**
- How users work (workflows vs expertise)
- Natural boundaries in technology
- Frequency of use (split high-use areas)

## Scaling Milestones

### Phase 1: MVP (1-2 skills)

**Goal:** Prove the concept

```
tech-mastery/
├── tech-docs/        (300 lines)
└── tech-patterns/    (350 lines)
```

**Budget:** 650 lines (~5k tokens)

**Validation:**
- Grep patterns work
- Cross-links function
- Users can discover docs

### Phase 2: Standard (3-4 skills)

**Goal:** Cover common use cases

```
tech-mastery/
├── tech-docs/        (350 lines)
├── tech-patterns/    (400 lines)
├── tech-advanced/    (450 lines)
└── tech-integration/ (350 lines)
```

**Budget:** 1550 lines (~12k tokens)

**Validation:**
- All workflows covered
- Skills compose well
- No duplication

### Phase 3: Comprehensive (5-7 skills)

**Goal:** Complete coverage

```
tech-mastery/
├── tech-docs/        (400 lines)
├── tech-getting-started/ (300 lines)
├── tech-patterns/    (400 lines)
├── tech-advanced/    (450 lines)
├── tech-testing/     (350 lines)
├── tech-integration/ (400 lines)
└── tech-migration/   (350 lines)
```

**Budget:** 2650 lines (~20k tokens)

**Validation:**
- Expert users satisfied
- Covers edge cases
- Still composable

### Phase 4: Specialized (8+ skills)

**Goal:** Deep expertise areas

**Warning:** Beyond 8 skills, consider splitting into multiple plugins.

**Example split:**

```
tech-core-mastery/          (core language/framework)
├── tech-docs/
├── tech-basics/
├── tech-patterns/
└── tech-advanced/

tech-ecosystem-mastery/     (integrations)
├── tech-ecosystem-docs/
├── tech-aws-integration/
├── tech-gcp-integration/
└── tech-docker-patterns/
```

## Token Budget Calculation

**Formula:**

```
Total Budget = (Skill Count × Average Lines per Skill) × Tokens per Line

Example:
5 skills × 400 lines × 1.5 tokens/line = 3000 tokens
```

**Line-to-token ratio:**
- Markdown text: ~1.2 tokens/line
- Code blocks: ~1.8 tokens/line
- Mixed content: ~1.5 tokens/line (average)

**Context window allocation:**
- Skills: 3-5k tokens
- Conversation history: 10-20k tokens
- User message: 1-2k tokens
- Available for response: 150-175k tokens

**Safe limit:** Keep all loaded skills under 20k tokens combined.

## Performance Optimization

### 1. Lazy Loading

```markdown
<!-- Instead of inline examples: -->
\```typescript
// 50 lines of example code
\```

<!-- Link to examples: -->
**Example:** `rg "PatternName" ../tech-docs/references/samples/ -A20`
```

**Benefit:** Load example only when user runs grep.

### 2. Conditional Sections

```markdown
<!-- Only include when relevant: -->
## PostgreSQL-Specific Patterns

*Skip this section if using MySQL*

\```sql
-- PostgreSQL patterns here
\```
```

**Benefit:** Users skip irrelevant sections mentally.

### 3. Summarization Tables

```markdown
<!-- Instead of 200 lines of function descriptions: -->

| Function | Purpose | Example |
|----------|---------|---------|
| JSON_VALUE | Extract scalar | `rg "JSON_VALUE" ../docs/` |
| JSON_QUERY | Extract object | `rg "JSON_QUERY" ../docs/` |

**Full reference:** `rg "JSON.*function" ../tech-docs/references/api-reference/`
```

**Benefit:** Table is ~50 lines vs 200 lines of prose.

### 4. Strategic Cross-Links

```markdown
<!-- Bad (duplicates content): -->
## Error Handling (in both tech-patterns and tech-advanced)
[100 lines of overlapping content]

<!-- Good (split responsibility): -->
## Error Handling (tech-patterns)
Basic try/catch patterns. For retry logic, see tech-advanced.

## Retry Patterns (tech-advanced)
Advanced retry with backoff. Assumes basic error handling from tech-patterns.
```

**Benefit:** 100 lines saved by splitting, not duplicating.

## Monitoring and Maintenance

### Budget Tracking

Create a budget spreadsheet:

| Skill | Current Lines | Budget | Status | Notes |
|-------|---------------|--------|--------|-------|
| tech-docs | 387 | 400 | 🟢 OK | -13 lines |
| tech-patterns | 425 | 400 | 🟡 WARN | +25 lines - refactor |
| tech-advanced | 512 | 500 | 🔴 OVER | +12 lines - SPLIT |

**Actions:**
- 🟢 OK: No action needed
- 🟡 WARN: Review for compression opportunities
- 🔴 OVER: Must split or compress before next release

### Line Count Check

```bash
# Quick check
wc -l plugins/tech-mastery/skills/*/SKILL.md

# Detailed report
for skill in plugins/tech-mastery/skills/*/SKILL.md; do
  lines=$(wc -l < "$skill")
  name=$(basename $(dirname "$skill"))
  printf "%-20s %4d lines\n" "$name" "$lines"
done | sort -k2 -nr
```

### Automated Validation

```bash
#!/bin/bash
# check-skill-budgets.sh

MAX_LINES=500
WARN_LINES=450

for skill in plugins/*/skills/*/SKILL.md; do
  lines=$(wc -l < "$skill")
  name=$(echo "$skill" | sed 's|plugins/||' | sed 's|/skills/|/|' | sed 's|/SKILL.md||')

  if [ "$lines" -gt "$MAX_LINES" ]; then
    echo "❌ $name: $lines lines (over budget by $((lines - MAX_LINES)))"
  elif [ "$lines" -gt "$WARN_LINES" ]; then
    echo "⚠️  $name: $lines lines (approaching limit)"
  else
    echo "✅ $name: $lines lines"
  fi
done
```

## Case Study: Spanner Mastery

**Initial approach (failed):**
- Single skill: 2500 lines
- Included all docs inline
- Context explosion, unusable

**Refactored (successful):**
```
spanner-mastery/
├── spanner-docs/      397 lines (grep patterns only)
├── spanner-googlesql/ 397 lines (SQL patterns + cross-links)
├── spanner-gql/       467 lines (GQL patterns + cross-links)
├── spanner-emulator/  ~300 lines (emulator patterns)
├── spanner-patterns/  ~350 lines (general patterns)
└── spanner-node-client/ ~300 lines (client SDK patterns)
```

**Total:** ~2600 lines across 6 skills (~20k tokens)

**vs monolithic:** 2500 lines in 1 skill (~30k tokens, but unusable due to poor organization)

**Result:**
- Each skill independently useful
- Skills compose well
- Users load only what they need
- Documentation (420 pages scraped) accessed via grep, not loaded

## Summary

**Key strategies for scaling:**

1. **Budget discipline:** Keep skills under 500 lines
2. **Horizontal scaling:** Split into multiple focused skills
3. **Vertical scaling:** Compress via grep patterns and cross-links
4. **Progressive disclosure:** Load only what's needed
5. **Strategic splits:** Organize by workflow, expertise, or technology area
6. **Monitor budgets:** Track line counts, enforce limits
7. **Reference don't duplicate:** Cross-link instead of copying

**Success metrics:**
- All skills < 500 lines individually
- Total plugin < 3000 lines across all skills
- Skills compose well (can load 2-3 simultaneously)
- Users can find anything in 1-2 grep searches
- No duplication between skills

**Remember:** The goal is infinite scale through finite budgets. Good architecture enables comprehensive documentation with minimal context usage.
