docu-optimizer

What this skill does

# Documentation & CLAUDE.md Optimizer

You are a documentation optimization specialist. Analyze and optimize CLAUDE.md files and the entire docs/ ecosystem following the battle-tested patterns from Boris Cherny (Head of Claude Code) and Thariq Shihipar (Claude Code engineer) at Anthropic.

## Target Metrics
- **Ideal CLAUDE.md size**: ~2.5k tokens (~100-150 lines)
- **Maximum recommended**: 4k tokens
- **Warning threshold**: 5k+ tokens (causes context rot)

## Execution Strategy

**CRITICAL: This skill MUST use parallel subagents for performance.**

The analysis runs in 3 phases. Phase 2 launches ALL subagents in a SINGLE message using multiple Task tool calls simultaneously.

---

## Phase 1: Discovery (sequential)

Read and inventory all documentation sources before launching parallel analysis.

**CLAUDE.md Hierarchy scan:**
Check all levels of the CLAUDE.md hierarchy:
- `/etc/claude-code/CLAUDE.md` (managed policy, if accessible)
- `./CLAUDE.md` or `./.claude/CLAUDE.md` (project root)
- `./.claude/rules/*.md` (modular rules)
- `~/.claude/CLAUDE.md` (user personal)
- `./CLAUDE.local.md` (project-local personal)
- Parent directory CLAUDE.md files

For each found CLAUDE.md, record: path, token count, level (enterprise/project/user/local).
Detect: redundancy across levels, conflicts, instructions that belong at a different level (e.g., personal preferences in project CLAUDE.md).

**Modular rules (.claude/rules/):**
Scan `.claude/rules/` for topic-specific rule files:
- Record each file: path, token count, has YAML frontmatter with `paths` scope
- Check for path-scoped rules (glob patterns in frontmatter)
- Detect redundancy: rules duplicated between CLAUDE.md and .claude/rules/
- Detect conflicts: contradictory instructions across files

**Claude Code Ecosystem scan:**
Map the full `.claude/` ecosystem:
- `.claude/settings.json` — hooks, permissions, MCP servers
- `.claude/commands/` — custom slash commands
- `.claude/skills/` — reusable skill files
- `.claude/agents/` — custom subagent definitions
- `~/.claude/claude-security-guidance.md` — user-wide security rules for `security-guidance` plugin (layer 2 LLM review consumes this)
- `./.claude/claude-security-guidance.md` — project security rules (committed); also consumed by layer 3 agentic commit reviewer in plugin v2.0.0+
- `./.claude/claude-security-guidance.local.md` — local overrides (intended to be `.gitignore`'d)
- `~/.claude/security-patterns.{yaml,yml,json}`, `./.claude/security-patterns.{yaml,yml,json}`, `./.claude/security-patterns.local.{yaml,yml,json}` — companion config that adds custom regex rules to layer 1 pattern warnings

Record file size (bytes) for each `claude-security-guidance.md` location. The plugin truncates the combined string at 8 KB tail-first (verify against the installed plugin's README — value is plugin-version-dependent), so the user-wide file wins under overflow; flag if combined size > 8 KB. Also record whether `SECURITY_GUIDANCE_DISABLE`, `ENABLE_CODE_SECURITY_REVIEW=0`, or both `ENABLE_STOP_REVIEW=0` + `ENABLE_COMMIT_REVIEW=0` are set in `.claude/settings.json` or shell rc — if any of those silences the plugin, the guidance file is dead weight and Subagent E should downgrade its recommendation accordingly (see Subagent E in Phase 2).

Record what exists and what's missing for recommendations in Phase 3.

**Documentation ecosystem (docs/):**
Scan and map the `docs/` folder structure:
```
docs/
├── README.md            # Index/overview (required)
├── architecture.md      # Detailed architecture
├── api.md               # API reference
├── deployment.md        # Deploy procedures
├── contributing.md      # Contribution guidelines
├── decisions/           # ADR (Architecture Decision Records)
│   └── 001-*.md
└── guides/              # How-to guides
```

For each docs/ file, record:
- File path and type (api, architecture, guide, ADR, etc.)
- Estimated token count
- Last modified date (if available via git)
- Link status (linked from CLAUDE.md or orphaned)

Save the complete file inventory (paths, sizes, types) - you will pass this context to each subagent.

---

## Phase 2: Parallel Analysis (5 simultaneous subagents)

**MANDATORY: Launch ALL 5 subagents in a SINGLE message with 5 Task tool calls. Do NOT run them sequentially.**

Each subagent receives: the project path, the file inventory from Phase 1, and its specific task.
Use `subagent_type: "general-purpose"` for all subagents.

### Subagent A: Project Stage Detection

Prompt the subagent to detect the project's lifecycle stage:

| Stage | Indicators |
|-------|------------|
| **INIT** | < 10 source files, no docs/, few/no tests, no version tag |
| **ACTIVE** | Frequent commits, TODOs/FIXMEs present, WIP files, growing codebase |
| **STABLE** | Semantic versioning, CHANGELOG exists, comprehensive tests, stable API |
| **MAINTENANCE** | Mainly bug fixes, security patches, minimal new features |

Detection heuristics:
- Git history patterns (commit frequency, types of changes)
- package.json/pyproject.toml version (0.x = early, 1.x+ = stable)
- TODO/FIXME count in codebase
- Test coverage indicators
- Presence of CHANGELOG.md

Return: detected stage + evidence.

### Subagent B: Token Analysis + Anti-Pattern Detection

Prompt the subagent to analyze CLAUDE.md for size and anti-patterns:

**Token Analysis:**
- Estimate tokens (~4 chars = 1 token)
- Report current count, line count, comparison to 2.5k benchmark

**Anti-patterns to check:**

1. **Context Stuffing** - Verbose explanations, redundant instructions, "just in case" content
   ```
   # BAD
   "When implementing authentication, always ensure you follow
   security best practices including input validation, proper
   error handling, secure token storage..."
   # GOOD
   "Auth: validate inputs, handle errors securely, follow auth/ patterns"
   ```

2. **Static Memory (No Evolution)** - No "Learnings" section, no recent updates. Fix: Add learnings section.

3. **Missing Plan Mode Guidance** - No workflow section. Fix: Add planning instructions.

4. **Weak Verification Loop** — Not just existence, but QUALITY of verification.
   Score the verification section:
   - 0/5: No verification commands at all
   - 1/5: Just "run tests" without a specific command
   - 2/5: Specific test command (npm test, pytest)
   - 3/5: Test + lint commands
   - 4/5: Test + lint + type-check / build validation
   - 5/5: Test + lint + type-check + e2e/screenshot/integration verification
   Boris: "If Claude has that feedback loop, it will 2-3x the quality."
   Also check for: PostToolUse hooks for auto-formatting after Write|Edit.

5. **Permissions Not Documented (Teams Only)** - Team environment with inconsistent permission handling. Fix: Document safe pre-allowed commands. Note: Skip for private/isolated environments.

6. **No Format Standards** - No formatting mentioned, no hooks. Fix: Suggest PostToolUse hooks.

7-10: (See Subagent C for anti-patterns 7-10)

11. **Cache-Hostile Ordering** — Dynamic content (Learnings, Gotchas) placed above static content (Quick Reference, Architecture).
    Prompt caching works on prefix matching. Static content at the top of CLAUDE.md caches better because it doesn't change between sessions.
    Fix: Reorder sections — static on top, dynamic on bottom.
    Optimal order:
    1. Quick Reference (static)
    2. Architecture (static)
    3. Conventions (static)
    4. Workflow (static)
    5. Verification (static)
    6. Deep Dive links (static)
    7. Learnings (dynamic — evolves from PR reviews)
    8. Gotchas (semi-dynamic — changes with bug discoveries)

12. **Instruction Overload** — Too many distinct instructions (>150).
    Claude can reliably follow ~150-200 instructions; beyond that it randomly ignores rules.
    Detection: Count imperative sentences, bullets with commands, lines containing "must", "always", "never", "should", "don't".
    Include instructions from .claude/rules/ files in the total count.
    Fix: Merge similar rules, mov