# refactor: prune narration and history comments · PR \#19559 · pingdotgg/t3code

[View on GitCafe](https://git.cafe/pingdotgg/t3code/pull/19559)

Repository: [pingdotgg/t3code](https://git.cafe/pingdotgg/t3code)

Visibility: public

State: merged

Source repository: pingdotgg/t3code

Source branch: refactor/prune-comments

Target branch: main

Head commit: 391c8d32d02b8f95b8dfa8d987444d5664ff4ef5

[Discussion and reviews](https://git.cafe/pingdotgg/t3code/pull/19559)

[Commits](https://git.cafe/pingdotgg/t3code/pull/19559/commits?format=markdown)

[Files changed](https://git.cafe/pingdotgg/t3code/pull/19559/diffs?format=markdown)

## Description

---

![Which version did the judges prefer? With comments 21, without comments 18, no difference 21, out of 60 blind verdicts.](https://uploads-production-47e4.up.railway.app/files/2e3bacbe-94c5-4728-896c-892b779dab64/chart-verdicts.png)

![Quality score by judge model, with vs without comments: Claude Opus 5.5 8.0 vs 7.9, GPT-6.1-Sol 8.5 vs 8.7, GPT-6-Astra 8.3 vs 8.5.](https://uploads-production-47e4.up.railway.app/files/bed666a9-2b3b-4c33-baf5-34624cae777a/chart-scores.png)

![Same work, same cost: checks passed 85% vs 95%, tokens 857k vs 844k, files read 7.9 vs 8.1, minutes 3.2 vs 3.0.](https://uploads-production-47e4.up.railway.app/files/7590205b-7d3e-4eb7-8f07-2ebfa9346d34/chart-effort.png)

Removes comments that repeat the code, document the obvious, or record history, in source and tests. Agents copy these into new files, where they go stale. A comment stays only when someone reading the code would likely break something without it: a security check, a race, a provider or OS quirk, or an invariant another file relies on. Lint directives, knip tags, and suppression reasons stay. Comment lines in the touched files drop from 63,684 to 18,432. Outside the lint rule below, code is unchanged: every pruned file parses to the same syntax tree as `main`.

A new `t3code/no-low-value-comments` lint rule keeps the mechanical cases out: section dividers, Arrange/Act/Assert labels, TODOs without an issue link, JSDoc types in TypeScript, empty `@param`/`@returns` tags, commented-out code, and comments that only repeat the name below them. `AGENTS.md` now tells agents that comments say why.

To check the effect on agents, gpt-6.1-sol did the same 10 tasks on `main` and on an earlier cut of this branch. 6 judges compared each pair without knowing which was which. 21 verdicts favored `main`, 18 favored the branch, and 21 were ties. Tokens, files read, and time stayed within 6%. The bench has not been rerun on this cut.

Done by claude-opus-5-5 (Claude Code) coordinating gpt-6.1-sol (Codex) subagents.