Summary
Follow-up from #938 / PR #942: clarify the PR size-budget guidance so agents do not reduce code readability merely to fit the ≤300 production LOC guideline.
Observed failure
While preparing the #938 trace harness report PR, the implementation briefly compressed scripts/trace-harness-report.py by removing normal blank lines between functions to keep the script under 300 physical lines. That made the file harder to read and review without improving behavior, tests, or maintainability.
The operator explicitly called this out as backwards: quality and readability should win over the line-count guideline.
Root cause
Primary cause: agent judgment failure. The existing AGENTS.md language already says the PR size budget is a review guideline, not a LOC-reduction mandate.
Secondary contributing gap: the rule and PR template can still be read by agents as a strong incentive to preserve within budget status at all costs. They do not explicitly forbid formatting/structure compression or instruct agents to choose size-gated: justified overage when the only alternative is lower readability.
Proposed change
Update the repo guidance in AGENTS.md and/or the PR template to make this invariant explicit:
- Do not collapse formatting, merge unrelated responsibilities, delete useful tests, or reduce readability solely to fit the size budget.
- If a PR is over budget because the smallest readable implementation plus tests needs the space, classify it as
size-gated: justified overage and seek the required human sign-off.
- Preserve code reviewability as part of the size gate; line-count reductions must come from real simplification or better decomposition, not cosmetic compression.
Acceptance criteria
Summary
Follow-up from #938 / PR #942: clarify the PR size-budget guidance so agents do not reduce code readability merely to fit the
≤300 production LOCguideline.Observed failure
While preparing the #938 trace harness report PR, the implementation briefly compressed
scripts/trace-harness-report.pyby removing normal blank lines between functions to keep the script under 300 physical lines. That made the file harder to read and review without improving behavior, tests, or maintainability.The operator explicitly called this out as backwards: quality and readability should win over the line-count guideline.
Root cause
Primary cause: agent judgment failure. The existing AGENTS.md language already says the PR size budget is a review guideline, not a LOC-reduction mandate.
Secondary contributing gap: the rule and PR template can still be read by agents as a strong incentive to preserve
within budgetstatus at all costs. They do not explicitly forbid formatting/structure compression or instruct agents to choosesize-gated: justified overagewhen the only alternative is lower readability.Proposed change
Update the repo guidance in
AGENTS.mdand/or the PR template to make this invariant explicit:size-gated: justified overageand seek the required human sign-off.Acceptance criteria
AGENTS.mdsize-budget guidance explicitly says readability-hostile compression is not allowed.size-gated: justified overageinstead of compressing code when readability is the tradeoff.