Repo bloat trimming: comment density is growing 3x faster than code

[spxrogers]

The measurement

Production Go only (*.go excluding *_test.go, excluding website/), comment lines vs code lines:

date	commit	comment	code	ratio
2026-06-18	8b2772b	5,816	18,375	0.32:1
2026-08-31	e452f7d	12,325	25,759	0.48:1
2026-09-02	0a45d0d	12,859	25,953	0.50:1

Over that window code grew +41% and comments grew +121%. Comment density is up 56%.

The marginal rate is worse than the average. Isolating recent PRs' production Go:

#240 (f6aa686 -> 0a45d0d):   +106 comment   +32 code   = 3.31 : 1

New production code is currently arriving with roughly three lines of prose per line of logic. That is the trend line to bend, not the absolute number.

What this is NOT

Worth stating so the cleanup doesn't overshoot:

• It is not a test problem. Test:production code is 2.07:1, and the test suites are what have been catching real defects. #240's diff looked alarming at +1088, but 877 of those lines (81%) are test code and only 164 are production Go. Tests are out of scope here.
• It is not pervasive. Only 12 of 140 production files with ≥40 code lines have more comment than code — 9%. The repo-wide average is dragged by a short list, not by a uniform habit.
• It is not "docs are bad". The docs/ contract pages and the website are a product surface for this project, and CLAUDE.md's doc-sync rule exists because stale prose has been a real defect class here. This issue is about density and payload, not about deleting documentation.

The actual failure mode

Reading the worst offenders, the excess is rarely "explains something subtle". It is mostly one of four things:

1. Review-history narration. Comments recording what a previous revision said, why a reviewer objected, and what changed — the archaeology of how the code got here, which git already stores. (#240 accumulated several of these and had to trim them back out mid-review, twice.)
2. Measurement transcripts. Full reproduction recipes and rc=124 tables inline in a doc comment, where a one-line statement of the invariant plus an issue link would do.
3. Restating the code. Prose that tracks the implementation line-for-line and must be re-edited whenever the implementation moves — which is how prose goes stale and starts lying.
4. Cross-package behaviour catalogues — one function's doc describing what four other commands do, which no local change can keep true.

The tell for (3) and (4): this repo has had a recurring defect class of comments asserting things the code does not do. That is a symptom of prose volume, not just prose carelessness. Less prose, more load-bearing, is also less to keep true.

Concrete targets

Production files ≥40 code lines, ranked by comment:code:

ratio	comment	code	file
2.57:1	293	114	internal/adapter/adapter.go
2.20:1	132	60	internal/untrusted/untrusted.go
1.67:1	216	129	internal/secrets/validate.go
1.64:1	202	123	internal/state/legacy.go
1.33:1	56	42	internal/adapter/adaptertest/stderr.go
1.27:1	124	98	internal/secrets/resolved.go
1.20:1	78	65	internal/cli/lock.go
1.19:1	210	176	internal/source/schema.go
1.09:1	166	152	internal/cli/upgrade_notice.go
1.09:1	98	90	internal/secrets/rereference.go
1.04:1	262	251	internal/ui/ui.go
1.02:1	128	126	internal/cli/root.go

Do not trim these blind. internal/secrets/* and internal/untrusted document invariants where a wrong edit is a security bug — the secret-leak fences and the terminal-escape defense. Those comments are the guardrail and several are explicitly cited by CLAUDE.md. The right move there is to tighten wording, not cut content, and to move worked examples and measurement transcripts to the issues that own them.

internal/adapter/adapter.go at 293 comment lines over 114 code lines is the clearest starting point: it is an interface definition, so most of its prose is contract description that could live once in docs/architecture.md rather than inline.

The bar to apply

Proposed test for any comment, to be applied when touching a file rather than as a big-bang sweep:

• Does it say something the code cannot? An invariant, a "why not the obvious thing", a measured hazard, a cross-file contract. Keep.
• Would a reader who knows Go infer it from the next five lines? Cut.
• Does it narrate a past revision or a review exchange? Cut — that is what git and the issue tracker are.
• Does it describe behaviour in another package? Move to the doc or issue that owns it; a stale pointer is worse than none.
• Is it a reproduction recipe or measurement table? One sentence of conclusion inline, the transcript in the issue.

Suggested acceptance

• Production comment:code back under 0.35:1 repo-wide (roughly the June baseline), without touching the secret/untrusted invariants except to tighten wording.
• No production file above 1.5:1 except with a one-line justification at the top of the file saying why.
• New PRs: production comment:code under 1:1 as a review heuristic, not a gate.

Note on provenance

The recent slope is substantially from agent-authored work, including mine in #237 and #240 — long explanatory comments are cheap for a model to produce and read as diligence, and the review process rewarded them until it started flagging them. Two review lenses independently called #240's prose disproportionate before this was raised. Worth treating the authoring habit as the thing to fix, not just the accumulated lines; a note in CLAUDE.md's code-conventions section would do more than a one-time sweep.

[spxrogers]

Decision to make once #247 lands: the fate of internal/cli/planwalk_characterization_test.go.

#244 added a ~1.1k-line characterization harness (27 fixtures × four golden projections) whose job was to prove the four-way merge of the plan→drift walk was lossless. That job is done when #247 merges: it edits the two goldens the harness header said it would, and after that the harness is either a regression suite for the walk's four callers or dead weight. It should be decided deliberately, with the #247 diff in view, rather than left by inertia. Three outcomes:

1. Keep it as-is. Cost: 1.1k lines that mostly re-pin what planwalk_internal_test.go, planwalk_order_internal_test.go, iss162, iss155 and the status/diff/reconcile/explain command tests already cover. Benefit: the only in-order oracle for status's whole-file→key→orphan partition and reconcile's items-then-orphans composition.
2. Fold the discriminating fixtures into the walk's unit tests and delete the rest. The review loop's mutation sweeps identified which fixtures were sole catchers (the two ordering fixtures, the emptied-section one, the two-agents-own-one-orphan one, the JSONC decoder one); the remaining ~20 are redundant with existing tests. This is the Repo bloat trimming: comment density is growing 3x faster than code #243-aligned option.
3. Retire it entirely. Only if the walk's own tests are first extended to cover the partition/composition contracts.

Recommendation is 2. Production is 271 lines; the test surface for it should not stay at seven times that once the migration it was proving is over.

---

Generated by Claude Code