/docs-check

name: docs-check
description: |
  CONTRIBUTOR TOOL - Validate plugin against latest Claude Code documentation.
  Catches breaking changes, deprecations, discovers new features.
  Run before releases or periodically. NOT part of the distributed plugin.
argument-hint: "[--quick|--focus=agents|skills|hooks|config]"

Plugin Documentation Compatibility Check

Validates plugin agents, skills, hooks, and config against the latest Claude Code documentation to catch breaking changes and discover new features.

Usage

/docs-check                    # Full validation (all components)
/docs-check --quick            # Structural checks only (no docs fetch, no tokens)
/docs-check --focus=agents     # Validate only agents
/docs-check --focus=skills     # Validate only skills
/docs-check --focus=hooks      # Validate only hooks
/docs-check --focus=config     # Validate only plugin.json/marketplace.json

Architecture (OTP Supervision Pattern)

┌─────────────────────────────────────────────────────────────────┐
│  /docs-check (skill entry point)                                │
│   │                                                             │
│   ├─ Step 1: bash scripts/fetch-claude-docs.sh (zero tokens)    │
│   │          Always fetches all 9 doc pages (~420KB)             │
│   │                                                             │
│   └─ Step 2: delegate to orchestrator (reads from cache only)   │
│       │                                                         │
│       │  docs-validation-orchestrator (opus)                    │
│       │                                                         │
│       │  SCAN → READ CACHE → SPAWN WORKERS → COMPRESS → REPORT │
│       │   │         │              │             │          │   │
│       │   ↓         ↓              ↓             ↓          ↓   │
│       │ inventory  pre-fetched  4 parallel    context    report │
│       │ plugin     docs-cache   subagents     supervisor       │
│       │ components              (sonnet)      (haiku)          │
│       └─────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────────┘

Execution

Step 1: Fetch Docs (Automatic)

**Always run first.** Downloads all doc pages to cache. Skips pages already cached within 24h. Zero token cost — pure curl.

# --quick mode: skip this step entirely (structural checks only)
# All other modes: always fetch
bash scripts/fetch-claude-docs.sh

Step 2: Delegate to Orchestrator

After docs are cached, delegate. The orchestrator reads from cache only and crashes if cache files are missing.

Task(subagent_type: "docs-validation-orchestrator")

Pass the user's flags (--quick, --focus) in the prompt.

What the Orchestrator Does

1. **Inventory** — scan `plugins/elixir-phoenix/` for existing components 2. **Read cached docs** — from `.claude/docs-check/docs-cache/` (never fetches) 3. **Spawn workers** — one sonnet subagent per component type, in parallel 4. **Compress** — context-supervisor (haiku) if 3+ workers 5. **Structural checks** — fast local checks, always run 6. **Report & Action** — write report, offer PR if issues found

Iron Laws

1. **Fetch ALL docs upfront** — no conditional fetching, no partial downloads 2. **Use `scripts/fetch-claude-docs.sh`** — single source of truth for doc fetching 3. **Workers get docs IN PROMPT** — no runtime fetching 4. **Workers use sonnet** — opus is wasteful for comparison tasks 5. **Structural checks always run** — even if docs fetch fails 6. **Breaking changes are BLOCKERS** — surface prominently

References

• `references/validation-rules.md` — Per-component validation checklists
• `references/doc-pages.md` — Component-to-URL mapping