Fixing doc bloat

Fixing Doc Bloat

Overview

The approved subset is your mandate — not the report's other findings, not the doc's overall bulk. You apply exactly the records the human approved by ID and nothing else. A bloat fix that also "cleans up" an obvious-but-unapproved finding stops being reviewable: a human can no longer tell an approved cut from your opinion of what should have been approved.

Acting on an unapproved record is violating the approval, even when the record is right.

Input: a validator-passing detecting-doc-bloat report ("schema": 2, records with id / doc / location / verdict / evidence / proposal / status / files) plus an explicit approval — {"approved": [ids]} from issue triage, or the human's in-session ID list. The approved records are the action items; every other record in the report is context, not a to-do. This skill applies the approved subset; it does not re-audit or re-classify.

REQUIRED SUB-SKILL: use writing-docs for any landing that needs real writing — an EXTRACT-AND-MOVE text or MERGE-DOC remainder that must read densely in its new home, not a string-swap.

Discipline spine: the generic apply rules — authorized-records-only, no while-I'm-here, anchor-confirm, blast-radius, evidence-travels — are owned by ${CLAUDE_PLUGIN_ROOT}/references/apply-discipline.md. Read it; this skill adds only the bloat-specific application below. The routing table, stops, red flags, and rationalization table here are in force unchanged.

Headless (group executor)

When the weekly workflow dispatches you as a matrix group executor, your approved subset arrived verbatim in the dispatch prompt — the record IDs (with verdict and doc) plus the report path. That list is the human approval and your entire mandate: apply exactly those records by the routing table, nothing else. Make one commit per applied record, in the order listed — the workflow transports your work as a per-record patch series, so an uncommitted landing does not exist and a multi-record commit cannot be merged record-by-record. A record you cannot apply is reported as skipped or failed with its stated reason — never a stopper for its siblings. Done means the per-record commits plus the group result object ({"group", "applied", "skipped", "failed"} — every listed id in exactly one array) written to the exact path the dispatch names; then stop. You never open the distill manifest, never push, never open a PR, and never merge — orchestration, retries, the merge, and the draft PR are the workflow's, not yours.

The routing table (the bloat-specific rules)

Apply each approved record by its verdict. For the passage verdicts, location is the passage's anchor (its first line) and the record's evidence opens with the passage's full extent — file:start-end (file:start if one line). The edit's mandate is the passage that span delimits, anchored at location — not mechanically the anchor line. The doc verdicts carry location: null and act on the whole doc.

Verdict	Applied as
CUT	delete the passage the record's evidence delimits, anchored at location (anchor-confirm first, per spine §3). On a boundary line the passage shares with unflagged text, delete only the passage's own text — the neighboring sentence's words stay
CONDENSE	replace the passage the record's evidence delimits — every line of its span — with proposal, byte-verbatim — the report drafted that text to the writing-docs bar; you place it, you do not touch it
EXTRACT-AND-MOVE	land proposal.text in proposal.target (writing-docs bar), delete the source passage the record's evidence delimits — one commit
RETIRE-DOC	delete the doc; approval of this ID is the deletion authorization — no second confirmation needed
MERGE-DOC	move the content not already in proposal.target into it, then delete the merged doc — one commit
DISTILL (status: "ready" only)	dispatch doc-lifecycle:doc-distiller with the record (its ID, the artifact path in doc, and its evidence); the distiller authors the claims/insights/decision entry post-approval and stages one commit, which you then commit. pending-implementation is never actionable — skip it with a note even if it was approved
POLICY	apply the record's proposal policy to exactly the paths in files — for a retirement-class policy, git rm those files in one commit. The files array is the complete mandate: never widen to the directory's current contents, never skip a listed path silently. A policy you cannot apply mechanically as stated → stop, surface it. Approval of this ID is the deletion authorization

Boundary rule — an approved edit's blast radius is that record's own location/proposal

The single boundary that RED broke: an approved record's edit reaches only its own location and its own proposal. A different record sitting one paragraph away — approved or not — is a separate action item. Never fold an adjacent record's content into an approved record's edit, even when the two are about the same subject and the report already wrote the adjacent record's text for you. If record X is approved and record Y is not, Y's line stays exactly as it is; the fact that X's fix touches nearby lines does not extend X's mandate to cover Y. Absorbing Y into X's diff is applying an unapproved record — a spine §1 violation — no matter which record's commit it hides in.

CONDENSE text lands as given — never blended, never augmented

A CONDENSE proposal is complete, writing-docs-bar text. Land it as-is, at its own boundary; stop at its final character. Do not merge a neighboring record's rationale into a CONDENSE line "so it reads fuller," do not append a fact the proposal didn't state, and do not restate the same fact in an adjacent sentence — a bloat fix that adds redundancy has failed at its own job. If you believe a CONDENSE proposal is incomplete, that is feedback for the human, not a license to rewrite it. "Applied verbatim" must be literally true of the bytes you wrote. The same hands-off rule covers everything the distiller lands: what it staged is what you commit — never re-edited, never "rounded out."

DISTILL is the distiller's job — dispatch, never inline

For an approved DISTILL ready record, dispatch the doc-lifecycle:doc-distiller agent with that one record; do not distill the artifact yourself. The distiller owns the method (single owner), and since contract v2 it also authors the residue — records carry no payload: post-approval, the distiller re-verifies the landing, runs the per-section insight walk, drafts claims (each verified against the code it cites), drafts artifact-true anchored insights (creating the target narrative doc with its > As of line if absent), appends one entry to docs/decisions.md (creating it with an # Decisions heading if absent — the decision log is a repo-level file, not a CLAUDE.md subsection), completes the Source: line with the artifact's real last-commit SHA, repoints the artifact's inbound references, and git rms the artifact — all staged as one commit, which you then commit. The distiller stages; the dispatcher commits. Match your dispatch input to its contract: hand it the record (ID, artifact path, evidence) plus the report path — the distiller deduplicates its landings against sibling records (e.g. an EXTRACT-AND-MOVE aimed at the same target), which it can only do if it can see them; expect back the residue as drafted, the claims and insights landed (with target:line), any that failed verification, duplicates skipped with the colliding record, references repointed, the log entry as written, and the staged file list — the drafted residue is what the approving human sees in the draft PR.

Distiller failure handling: if the distiller reports a claim failed verification, that claim is simply not landed — surface the failure to the human; never redraft the claim yourself to force it through. Land what verified, report what didn't. If the distiller reports a collision (a DISTILL claim and a sibling EXTRACT record aimed near-duplicate text at one target), it already deduped its side and landed the line once — pass its collision note through to the human; never re-edit the landed result to "reconcile" it.

Bloat-specific stops

• Approved ID not in the report → stop. The inputs disagree; the approval references a record that isn't there. Do not guess which record was meant.
• DISTILL approved but status: "pending-implementation" → skip it, note it. There is no landed code to verify claims against, so nothing is actionable. Approval cannot make an unverifiable future-design into an edit.
• Distiller reports failed claims, or refuses because the landing re-verify failed → land what verified, surface the failures. Never redraft its claims yourself to force one through.
• POLICY approved but a files entry no longer exists → apply the rest, note the missing path — never widen the edit to the directory's current contents to "compensate".
• A doc-level verdict (RETIRE-DOC / MERGE-DOC) and a passage verdict both approved for the same doc → apply the passage edits first, the doc-level delete/merge last. Deleting the doc first would strand the passage edits.

Red flags — STOP

• About to apply a record that isn't in the approval — "the CUT is unapproved but obviously right" → unapproved = not your mandate; surface it, don't apply it.
• Folding an adjacent (approved or unapproved) record's content into an approved record's edit → that adjacent record is a separate action item; its boundary is its own.
• Editing only the single line at location when the evidence span is multi-line, or deleting a whole boundary line that also carries unflagged text → the mandate is the span'd passage exactly: all of it, nothing beside it.
• Rewording, extending, or blending a CONDENSE proposal, or re-editing text the distiller landed → it lands byte-verbatim at its own boundary; adding to it re-introduces the bloat you're removing.
• Distilling the artifact inline instead of dispatching the distiller → the distiller owns the method; inlining it drops the re-verify / dedup / decision-log / single-commit shape.
• Putting the decision entry anywhere but docs/decisions.md (e.g. a CLAUDE.md subsection) → the decision log is a repo-level file; the distiller owns it.
• Redrafting a claim the distiller failed to verify, or re-editing a landed result it flagged for collision → surface it; don't launder or reconcile.
• Applying a POLICY record to files beyond its files array ("two new artifacts appeared — same class, I'll retire them too") → the array is the mandate; new files are a finding for the next sweep.
• Approving IDs yourself, or treating your presented summary as the approval → only the human's ID list is the mandate.
• Splitting an EXTRACT-AND-MOVE, MERGE-DOC, or DISTILL across commits → the move and the deletion ride one commit, or the diff stops reading "moved, not lost."
• Pushing, opening a PR, or folding several records into one commit as a group executor → one commit per record, the group result file, stop; the merge and the draft PR are the workflow's.
• Applying DISTILL pending-implementation because it was approved → skip + note; approval can't make unverifiable claims verifiable.

Rationalization table

Excuse	Reality
"The CUT is unapproved but trivial / obviously right"	Unapproved = not your mandate. Surface it; the human decides.
"This unapproved record is right next to my approved edit — I'll just include it"	Its boundary is its own location/proposal, not your approved record's. Absorbing it is applying an unapproved record.
"location names one line, so I'll only touch that line"	location is the anchor; the evidence's opening file:start-end span is the mandate. A CONDENSE of a nine-line passage replaces nine lines.
"The proposal reads thin — I'll round it out with the adjacent claim"	Land it byte-verbatim, stop at its boundary. Blending it in adds redundancy and breaks "applied as given."
"I'll just distill inline — dispatching is overhead"	The distiller owns the method (single owner). Inlining drops re-verify, dedup, the decision log, and the single-commit shape.
"The decision entry fits fine in CLAUDE.md"	The decision log is docs/decisions.md, a repo-level file the distiller owns.
"Pending artifact, but the human approved it"	Approval can't make unverifiable claims verifiable. Skip + note.
"The distiller couldn't verify a claim, but it's clearly true — I'll patch it in"	Land only what verified; surface the failure. Redrafting its claims launders an unchecked one.
"The policy obviously covers the new files in that directory too"	The approved files array is the mandate — filter-selected provenance, not a standing license over the directory.