What happened
The retro agent analyzed PR #2885 (which mechanically applied tier terminology prefixes across 28 files, producing degraded prose) and filed issue #2914 proposing that AGENTS.md be updated with detailed guidance: first-mention-then-abbreviate rules, compound adjective limits, and classify-before-transforming instructions. An external contributor implemented this in PR #2930 (+15/-1 lines to AGENTS.md). A maintainer (ralphbean) closed it without merge, stating the value gained by increased clarity did not outweigh the additional context loaded into AGENTS.md. The retro agent's proposed fix directly conflicted with the agent-scaffolding principle that context files should be minimal and every line should prevent a mistake the agent wouldn't otherwise make.
What could go better
The retro agent optimized for closing the gap it identified (mechanical terminology application) without considering whether adding prose to AGENTS.md was the right fix mechanism. AGENTS.md is a high-traffic context file loaded on every agent run — additions carry a real token cost. In this case, alternatives existed: a code-agent skill teaching the first-mention-then-abbreviate pattern for editorial tasks, a hook or lint rule enforcing compound adjective length, or a more concise single-line addition rather than 15 lines of guidance. The retro agent defaulted to 'add more documentation' when 'add enforcement' or 'add a skill' would have been more proportionate. Confidence is medium — this is one instance, not a confirmed pattern, though the large backlog of retro-filed issues (90+ open with agent/retro) suggests context file bloat pressure may be systemic.
Proposed change
Update the retro agent definition or its skill/prompt to include guidance: when proposing changes to context files (AGENTS.md, CLAUDE.md, agent definitions), the retro agent should (1) consider whether a hook, lint rule, or on-demand skill could enforce the same behavior deterministically, (2) prefer enforcement mechanisms or skills over prose additions to root context files, and (3) when prose is the only viable mechanism, keep additions to 1-2 lines and note the context budget trade-off explicitly so reviewers can make an informed decision. This guidance should live in the retro agent's prompt or definition, not in AGENTS.md itself (which would be ironic). Related but distinct from #2502 (fix proportionality for single-instance findings) — this proposal is specifically about the choice of fix mechanism for context files.
Validation criteria
Over the next 10 retro proposals that target AGENTS.md or similar context files, at least half should either propose an enforcement mechanism (hook, lint rule, skill) instead of prose, or explicitly acknowledge the context budget trade-off. No retro proposal should recommend adding more than 5 net lines to AGENTS.md without justifying why a hook or skill cannot achieve the same outcome.
Generated by retro agent from #2930
What happened
The retro agent analyzed PR #2885 (which mechanically applied tier terminology prefixes across 28 files, producing degraded prose) and filed issue #2914 proposing that AGENTS.md be updated with detailed guidance: first-mention-then-abbreviate rules, compound adjective limits, and classify-before-transforming instructions. An external contributor implemented this in PR #2930 (+15/-1 lines to AGENTS.md). A maintainer (ralphbean) closed it without merge, stating the value gained by increased clarity did not outweigh the additional context loaded into AGENTS.md. The retro agent's proposed fix directly conflicted with the agent-scaffolding principle that context files should be minimal and every line should prevent a mistake the agent wouldn't otherwise make.
What could go better
The retro agent optimized for closing the gap it identified (mechanical terminology application) without considering whether adding prose to AGENTS.md was the right fix mechanism. AGENTS.md is a high-traffic context file loaded on every agent run — additions carry a real token cost. In this case, alternatives existed: a code-agent skill teaching the first-mention-then-abbreviate pattern for editorial tasks, a hook or lint rule enforcing compound adjective length, or a more concise single-line addition rather than 15 lines of guidance. The retro agent defaulted to 'add more documentation' when 'add enforcement' or 'add a skill' would have been more proportionate. Confidence is medium — this is one instance, not a confirmed pattern, though the large backlog of retro-filed issues (90+ open with
agent/retro) suggests context file bloat pressure may be systemic.Proposed change
Update the retro agent definition or its skill/prompt to include guidance: when proposing changes to context files (AGENTS.md, CLAUDE.md, agent definitions), the retro agent should (1) consider whether a hook, lint rule, or on-demand skill could enforce the same behavior deterministically, (2) prefer enforcement mechanisms or skills over prose additions to root context files, and (3) when prose is the only viable mechanism, keep additions to 1-2 lines and note the context budget trade-off explicitly so reviewers can make an informed decision. This guidance should live in the retro agent's prompt or definition, not in AGENTS.md itself (which would be ironic). Related but distinct from #2502 (fix proportionality for single-instance findings) — this proposal is specifically about the choice of fix mechanism for context files.
Validation criteria
Over the next 10 retro proposals that target AGENTS.md or similar context files, at least half should either propose an enforcement mechanism (hook, lint rule, skill) instead of prose, or explicitly acknowledge the context budget trade-off. No retro proposal should recommend adding more than 5 net lines to AGENTS.md without justifying why a hook or skill cannot achieve the same outcome.
Generated by retro agent from #2930