What happened
PR #2885 standardized bare 'Tier N' references into prefixed forms (e.g., 'credential delivery tier 1') across 28 files. The agent applied the prefix to every single occurrence, including within sections already scoped to one tier type. This produced severely degraded prose: 'higher-intent-authorization-tier authorization' as a compound adjective, 'credential delivery tier' repeated 10 times in a 5-sentence paragraph in ADR 0032, and 'intent authorization tier 0' repeated 7 times in 7 consecutive bullets in a section titled 'Tier 0: Standing rules.' The agent also incorrectly changed 'compatibility tier' to 'compatibility classification' in agent-compatible-code.md — a term that was not one of the three defined tier types and should have been left unchanged per the convention's own exemption for external/unrelated tier references.
What could go better
The code agent treated a nuanced editorial task as a mechanical find-and-replace. Issue #935 covers a related pattern for code paths, but the docs case is distinct: prose readability requires the 'first-mention-then-abbreviate' pattern that technical writers use routinely. Within a section already scoped to one tier type (by heading, opening sentence, or surrounding context), repeating the full prefix on every occurrence actively harms readability. I am highly confident this is an improvement — compound adjectives like 'higher-intent-authorization-tier' are objectively harder to parse than 'higher-tier' in an already-scoped context. The semantic error (changing 'compatibility tier') also suggests the agent did not carefully evaluate whether each instance actually belonged to one of the three defined tier systems before transforming it.
Proposed change
Update AGENTS.md's terminology convention (added in this PR) to explicitly state: 'Use the descriptive prefix at first mention in each section or paragraph, then use bare Tier N for subsequent references within the same context. Do not create compound adjectives longer than three hyphenated words.' Additionally, add guidance to the code agent definition that when applying a codebase-wide terminology convention, the agent should: (1) classify each instance before transforming it, skipping instances that don't match the defined categories, and (2) apply the first-mention-then-abbreviate pattern rather than prefixing every occurrence. This is a repo-specific AGENTS.md change for the convention itself, plus a potential upstream improvement to the code agent's general approach to terminology/naming convention tasks.
Validation criteria
The AGENTS.md terminology convention should include first-mention-then-abbreviate guidance. The next code agent PR applying a naming convention across multiple files should not produce compound adjectives longer than 3 hyphenated words, and should not repeat a qualifying prefix more than twice per paragraph when context is already established.
Generated by retro agent from #2885
What happened
PR #2885 standardized bare 'Tier N' references into prefixed forms (e.g., 'credential delivery tier 1') across 28 files. The agent applied the prefix to every single occurrence, including within sections already scoped to one tier type. This produced severely degraded prose: 'higher-intent-authorization-tier authorization' as a compound adjective, 'credential delivery tier' repeated 10 times in a 5-sentence paragraph in ADR 0032, and 'intent authorization tier 0' repeated 7 times in 7 consecutive bullets in a section titled 'Tier 0: Standing rules.' The agent also incorrectly changed 'compatibility tier' to 'compatibility classification' in
agent-compatible-code.md— a term that was not one of the three defined tier types and should have been left unchanged per the convention's own exemption for external/unrelated tier references.What could go better
The code agent treated a nuanced editorial task as a mechanical find-and-replace. Issue #935 covers a related pattern for code paths, but the docs case is distinct: prose readability requires the 'first-mention-then-abbreviate' pattern that technical writers use routinely. Within a section already scoped to one tier type (by heading, opening sentence, or surrounding context), repeating the full prefix on every occurrence actively harms readability. I am highly confident this is an improvement — compound adjectives like 'higher-intent-authorization-tier' are objectively harder to parse than 'higher-tier' in an already-scoped context. The semantic error (changing 'compatibility tier') also suggests the agent did not carefully evaluate whether each instance actually belonged to one of the three defined tier systems before transforming it.
Proposed change
Update AGENTS.md's terminology convention (added in this PR) to explicitly state: 'Use the descriptive prefix at first mention in each section or paragraph, then use bare Tier N for subsequent references within the same context. Do not create compound adjectives longer than three hyphenated words.' Additionally, add guidance to the code agent definition that when applying a codebase-wide terminology convention, the agent should: (1) classify each instance before transforming it, skipping instances that don't match the defined categories, and (2) apply the first-mention-then-abbreviate pattern rather than prefixing every occurrence. This is a repo-specific AGENTS.md change for the convention itself, plus a potential upstream improvement to the code agent's general approach to terminology/naming convention tasks.
Validation criteria
The AGENTS.md terminology convention should include first-mention-then-abbreviate guidance. The next code agent PR applying a naming convention across multiple files should not produce compound adjectives longer than 3 hyphenated words, and should not repeat a qualifying prefix more than twice per paragraph when context is already established.
Generated by retro agent from #2885