Detecting doc bloat

Detecting Doc Bloat

Drift asks whether a doc is accurate; bloat asks whether it still earns its tokens. This skill is a thin router: deterministic scripts plan and validate the sweep; per-need references carry the verdict rules; you supply judgment one bounded chunk at a time. Three non-negotiables:

1. A verdict requires evidence. Every record names the file:line, quote, or grep that proves the finding — never "feels redundant".
2. The result is structured, not prose. Records per output-contract.md, validated mechanically at every seam. Approval of record IDs is the only bridge from a finding to a file change.
3. Read-only — this skill never edits. A human approves IDs; fixing-doc-bloat applies the approved subset.

Doc kinds (the planner hints these; override only with stated evidence)

• living — claim-style docs tracking the repo (README, CLAUDE.md, runbooks, reference). Rules: references/verdict-lenses.md.
• narrative — opens with growing-docs' > As of anchor (the file's first line, or the first line under the title), wherever the file sits. Own bar; never a planning artifact. Rules: verdict-lenses.md.
• planning — designs/specs/plans describing an intended change. Rules: references/planning-artifacts.md.
• A policy chunk (directory declared policy_scope in the repo's .github/doc-sync/audit-scope.json) yields exactly one POLICY record. Rules: planning-artifacts.md.

Modes

Interactive, small scope (the planner projects ≲2 chunks): sweep inline with the reference rules, emit one wrapped {"schema": 2, ...} report, run it through the validator before presenting anything.

Interactive, large scope: never sweep inline. Run the planner — its manifest is your work order as orchestrator; do not enumerate or read the corpus yourself — then dispatch one subagent per pending chunk, in concurrent waves of several, never serially (chunks are independent; a serial walk of a bootstrap-scale manifest is hours of avoidable wall-clock). Render each dispatch with --emit-prompt (the chunk's slice verbatim: doc list or policy dir + files, output path, definition of done) and point the subagent at (i) output-contract.md and (ii) only the reference file(s) its chunk's kinds need — verdict-lenses.md for living/narrative, planning-artifacts.md for planning and policy chunks. Each subagent writes {"chunk": "<id>", "records": [...]} to chunks/<id>.json under its working directory — the dispatch prompt names the exact path; seam-validate each result as it lands; a failing chunk is re-dispatched fresh once, then you stop and name it. Assemble the valid results into the final report.

Headless (chunk executor): your chunk slice arrived verbatim in the dispatch prompt — the doc list (or policy dir + files) and the output path. That slice is your entire scope: judge exactly those docs with the reference rules, write the chunk result, stop. You never open the manifest — it is the orchestrator's state, and it may not even be on disk; budgets, retries, and assembly are likewise the workflow's, not yours. A policy chunk means one POLICY record, files copied verbatim from the dispatch.

Script invocation templates

# plan (inventory -> chunk manifest; size + projected invocations on stderr).
# To narrow scope, pass --config with exclude/include globs (include re-adds what
# it matches); policy_scope/chunking keys are documented in the script docstring.
# Chunk ids are content-addressed, so --results-dir resume skips only chunks
# whose docs are unchanged; each chunk carries its model-invocation turn budget.
python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-doc-bloat/scripts/plan-chunks.py \
  --out <dir>/manifest.json --results-dir <dir>/chunks

# render one chunk's dispatch prompt / turn budget (slice verbatim — the
# executor never opens the manifest)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-doc-bloat/scripts/plan-chunks.py \
  --emit-prompt <id> --manifest <dir>/manifest.json
python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-doc-bloat/scripts/plan-chunks.py \
  --emit-turns <id> --manifest <dir>/manifest.json

# seam-validate one chunk result
python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-doc-bloat/scripts/validate-bloat-output.py \
  --chunk <dir>/chunks/<id>.json --manifest <dir>/manifest.json

# assemble all chunk results into the final report (refuses partial assembly)
python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-doc-bloat/scripts/validate-bloat-output.py \
  --assemble <dir>/chunks --manifest <dir>/manifest.json --out bloat-report.json

# validate a final wrapped report
python3 ${CLAUDE_PLUGIN_ROOT}/skills/detecting-doc-bloat/scripts/validate-bloat-output.py bloat-report.json

The contract

Records carry exactly id, doc, location, verdict, evidence, proposal, status, files; verdicts are CUT / CONDENSE / EXTRACT-AND-MOVE / RETIRE-DOC / MERGE-DOC / DISTILL / POLICY; the final report is wrapped with "schema": 2. DISTILL records carry classification + landed-code evidence only — the claims/insights/decision-entry authoring is the doc-distiller agent's post-approval job, dispatched by fixing-doc-bloat. Field rules, the worked example, and the chunk-result seam shape: output-contract.md. Never hand off anything the validator rejects.

REQUIRED SUB-SKILL: use writing-docs for every replacement or extraction text you propose (CONDENSE proposals, EXTRACT-AND-MOVE text) — dense, anchored, no narrative.

Presenting to a human

When a human triages in-session, render the report — never paste raw JSON as the summary:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/scheduling-doc-sync/scripts/render-report.py \
  bloat-triage --report bloat-report.json

Then ask for the approved IDs. Nothing you present is authorization on its own; the human's ID list is what fixing-doc-bloat receives.

Red flags — STOP

• A prose report with no structured records, or an invented verdict → the seven enum values, the contract shape, nothing else.
• Evidence asserted, not shown ("the sections are identical", no quote) → go get the line or the quoted overlap.
• Skipping the validator at an orchestrator seam — chunk results as they land, the final report → run it; never hand off a result it rejects. (As a headless executor, seam validation is the workflow's own step — never a license to open the manifest.)
• Authoring DISTILL claims/insights/decision entries at detect time — anywhere, including inside evidence → post-approval distiller work; emit the classification and proof only.
• Walking a policy chunk file-by-file, or a files list that isn't the dispatch's verbatim → one POLICY record per policy chunk.
• Opening the manifest, or enumerating the corpus, as a chunk executor → your slice arrived in the dispatch prompt; audit exactly it and stop.
• Sweeping inline when the planner projects >2 chunks → dispatch per chunk; the manifest is the orchestrator's work order, each executor's is its dispatched slice.
• Editing, deleting, or "just fixing the small one" → read-only; surface it as a record and stop.