/docs-drift

name: docs-drift
description: Use to catch documentation that has silently gone stale — it spawns ONE fresh sibling session via CCC that extracts every checkable factual claim from a doc (API fields, endpoint names, CLI flags, config keys, file paths, version numbers, example commands) and verifies each one against the actual code, reporting each mismatch as a drift with severity. A claim-by-claim audit, not a read-through.
allowed-tools: Bash

Docs-drift spawns a single fresh CCC session that treats a doc as a list of **factual assertions about the code** and checks each one against the source. It does not follow the docs as a user would — it enumerates the claims (this endpoint exists, this flag is `--foo`, this response has field `bar`, this default is `127.0.0.1`, this version is `X.Y.Z`) and greps/reads the code to confirm or refute each. The output is a drift ledger. It builds on the spawn/report_to mechanics in the `ccc-orchestration` skill — read that first for the full Spawn/Inject/Ask API.

Cost

**1 spawned session.** Each spawn is a real billed session on the user's kanban — tell the user the count before spawning. Point it at a **bounded** set of docs (one file, or a section) — "audit all the docs" is a fleet job (`fleet-lane-dispatch` with a per-doc brief), not one session.

Setup

CCC_URL="$(cat ~/.claude/command-center/port.txt 2>/dev/null || echo "${CCC_URL:-http://127.0.0.1:8090}")"
curl -sf --max-time 2 "$CCC_URL/api/version" >/dev/null 2>&1 || CCC_URL="http://127.0.0.1:8090"
curl -sf --max-time 2 "$CCC_URL/api/version" >/dev/null 2>&1 || CCC_DOWN=1

• (a) Run every CCC curl with the **network sandbox disabled** — the Bash

sandbox blocks loopback and fails spuriously even when CCC is up.

• (b) **URL-encode `repo_path`** in query strings (`+` → `%2B`, space → `%20`).
• (c) Resolve your own session id: `$CLAUDE_SESSION_ID`, else the newest

`*.jsonl` under `~/.claude/projects/<slugified-cwd>/` (see `ccc-orchestration`).

Preconditions — decide these BEFORE spawning

• **(a) The exact doc(s)** to audit — file paths or a named section. One file or

one section per run; the more bounded, the sharper the ledger.

• **(b) The source of truth** — which code the claims should match (a module, a

set of endpoints, a config schema). If you don't tell it where the truth lives, it wastes the run hunting.

• **(c) The claim types that matter** for this doc — API response fields, CLI

flags, endpoint paths, config keys/defaults, file paths, version strings, copy-paste example commands. Naming them focuses the extraction.

Spawning the auditor

curl -s -X POST "$CCC_URL/api/sessions/spawn" -H "Content-Type: application/json" -d @- <<'JSON'
{
  "prompt": "Audit this doc for drift against the code. DOC: <path or section>. SOURCE OF TRUTH: <module / endpoints / config to check against>. Method: 1) Extract EVERY checkable factual claim the doc makes about the code — endpoint paths, request/response field names, CLI flags, config keys and their stated defaults, file paths, version strings, and any copy-paste example command. Ignore prose, motivation, and opinion; only claims a reader could act on and be wrong. 2) For EACH claim, verify it against the actual code (grep / read the source — do NOT trust the doc). 3) Classify each: MATCH (doc agrees with code), DRIFT (doc contradicts code — wrong field name, renamed flag, changed default, dead endpoint, stale version), or UNVERIFIABLE (could not locate the truth — say why). Report ONLY the DRIFT and UNVERIFIABLE rows as a ledger; give a MATCH count as one summary number. Each drift row: the exact doc quote + line, what the code actually says (with file:line evidence), severity (BROKEN = a reader following this will fail, e.g. dead endpoint or wrong flag / MISLEADING = works but the doc is wrong, e.g. stale default / COSMETIC = typo-level), and the one-line doc patch. Finish with a verdict: is this doc safe to trust as-is, yes or no?",
  "repo_path": "/abs/path/to/repo",
  "report_to": "<your-session-id>"
}
JSON

Omit `"model"` and `"reasoning_effort"`: the server spawn defaults (Settings → Spawn defaults) apply. Pass either explicitly to keep cost down, with `"engine"` alongside it, since both are validated per engine (see `ccc-orchestration` § 2 for the per-engine effort ladders). CCC appends the return-address footer (`report_to`), so the auditor injects its ledger back to you when it finishes.

Waiting for the report

After spawning, **end your turn.** Tell the user an auditor is checking the doc against the code and give its session id. The ledger arrives by injection (`report_to`) — do **not** poll or sleep-loop. If it never arrives, check `GET /api/sessions/spawned` for whether the child is still alive.

When the report arrives

Turn the ledger into doc fixes:

• **BROKEN** drift is a doc bug that will actively mislead — fix before the next

reader hits it (a dead `/api/*` endpoint, a renamed flag, a wrong required field). For a public repo these ship the moment you push, so treat them like code bugs.

• **MISLEADING** — the reader gets through but on wrong information (a stale

default, an old version string); correct the wording.

• **COSMETIC** — polish when convenient.
• **UNVERIFIABLE** rows are their own signal — either the doc is describing

something that no longer exists, or the truth moved; investigate each.

Dry run

If the arguments contain `dry-run`, print the exact payload — session count (1), the full auditor prompt with the doc path and source-of-truth filled in, and the target repo — and POST nothing.

When CCC is down

If `CCC_DOWN=1` or the spawn curl returns connection refused (exit 7), fall back to the built-in `Task` tool subagent with the same claim-extraction prompt — fresh context matters less here than for `dogfood`, because the value is the systematic cross-check, not naïve eyes. You lose only kanban visibility. Never pretend the CCC spawn ran