What happened
In PR #6239, the code agent added a formatRef function that changed the repos status REF column from displaying full 40-character SHAs to truncated 7-character SHAs with expected ref annotation (e.g., 6f8b968 (main)). However, the code agent did not update the corresponding documentation in docs/cli/repos.md, which still described the REF column as showing refs like @v2.3.0, @main. The review agent caught this as a medium-severity stale-doc finding, and the fix agent subsequently updated the docs.
The AGENTS.md file contains a doc-update rule, but it is scoped to "removing or renaming a CLI command, public API, or user-facing feature." Since the code agent changed the output format rather than removing or renaming anything, the rule did not apply, and the agent skipped the doc grep.
What could go better
The AGENTS.md doc-update rule's scope is too narrow. Changing the behavior or output format of a user-facing feature is just as likely to create stale documentation as removing or renaming it. The code agent had explicit guidance to grep docs on removal/rename but no guidance for format changes, so it produced a valid but incomplete PR that required a fix cycle.
This is a high-confidence finding: the rule text is unambiguous in its current scope, the code agent followed it correctly (it just didn't apply), and the fix is a minimal wording change. Issue #5848 proposes a new bullet for CLI flag behavior changes, which is related but narrower — this proposal amends the existing rule to cover the broader class of behavioral changes.
Proposed change
In AGENTS.md, amend the existing doc-update rule from:
When removing or renaming a CLI command, public API, or user-facing feature, grep all documentation files under docs/ for references to the old name and update or remove them.
To:
When removing, renaming, or changing the behavior or output format of a CLI command, public API, or user-facing feature, grep all documentation files under docs/ for references and update them to reflect the current behavior. Pay special attention to docs/cli/, docs/guides/, and any getting-started or operations guides.
This is a single-line edit in the existing rule — no new bullets or sections needed.
Validation criteria
Over the next 5 code agent PRs that change CLI output format or behavior in this repo, the code agent should proactively update corresponding docs under docs/cli/ without requiring a review agent stale-doc finding or a fix cycle. Track by checking whether review agent runs on those PRs produce stale-doc findings — the count should drop to zero for changes covered by the broadened rule.
Generated by retro agent from #6239
What happened
In PR #6239, the code agent added a
formatReffunction that changed therepos statusREF column from displaying full 40-character SHAs to truncated 7-character SHAs with expected ref annotation (e.g.,6f8b968 (main)). However, the code agent did not update the corresponding documentation indocs/cli/repos.md, which still described the REF column as showing refs like@v2.3.0,@main. The review agent caught this as a medium-severity stale-doc finding, and the fix agent subsequently updated the docs.The AGENTS.md file contains a doc-update rule, but it is scoped to "removing or renaming a CLI command, public API, or user-facing feature." Since the code agent changed the output format rather than removing or renaming anything, the rule did not apply, and the agent skipped the doc grep.
What could go better
The AGENTS.md doc-update rule's scope is too narrow. Changing the behavior or output format of a user-facing feature is just as likely to create stale documentation as removing or renaming it. The code agent had explicit guidance to grep docs on removal/rename but no guidance for format changes, so it produced a valid but incomplete PR that required a fix cycle.
This is a high-confidence finding: the rule text is unambiguous in its current scope, the code agent followed it correctly (it just didn't apply), and the fix is a minimal wording change. Issue #5848 proposes a new bullet for CLI flag behavior changes, which is related but narrower — this proposal amends the existing rule to cover the broader class of behavioral changes.
Proposed change
In
AGENTS.md, amend the existing doc-update rule from:To:
This is a single-line edit in the existing rule — no new bullets or sections needed.
Validation criteria
Over the next 5 code agent PRs that change CLI output format or behavior in this repo, the code agent should proactively update corresponding docs under
docs/cli/without requiring a review agent stale-doc finding or a fix cycle. Track by checking whether review agent runs on those PRs produce stale-doc findings — the count should drop to zero for changes covered by the broadened rule.Generated by retro agent from #6239