What happened
On PR #5596, the code agent and human reviewer spent 5 review iterations discovering that repos upgrade is documented in 7 distinct locations. The repo's AGENTS.md contains guidance about checking sidebar config when adding new docs, but has no guidance about which existing documentation locations need updating when CLI command behavior changes. The contributing guides cover Go conventions, shell scripting, ADRs, and other topics but include no documentation update guide. Both agents and humans lack a reference for discovering all documentation touchpoints for a given CLI command group.
What could go better
A documentation cross-reference — mapping CLI command groups to the files that describe them — would help both agents and human contributors update all locations in one pass. This is a structural gap in the repo: the repos command group is described across docs/cli/repos.md, docs/guides/getting-started/operations.md, docs/guides/dev/cli-internals.md, docs/ADRs/0057-repos-management.md, and docs/plans/repos-management.md, plus inline CLI help text in internal/cli/repos.go. Without a cross-reference, contributors must discover these locations by trial and error or review feedback. Confidence is moderate — this would help, but it only works if agents and humans actually consult it. The triage agent change (proposed separately) is the more reliable mechanism since it automates discovery.
Proposed change
Add a section to AGENTS.md or create a new docs/contributing/documentation.md guide that maps CLI command groups to their documentation touchpoints. For the repos command group, this would list: (1) docs/cli/repos.md — CLI reference with command table and detailed sections, (2) docs/guides/getting-started/operations.md — operations guide command table, (3) docs/guides/dev/cli-internals.md — CLI reference tree with flags, (4) docs/ADRs/0057-repos-management.md — ADR Decision section (use annotations, not inline edits per ADR conventions), (5) docs/plans/repos-management.md — implementation plan, (6) internal/cli/repos.go — cobra command Short/Long descriptions. Include similar mappings for other major command groups (agent, mint, app, etc.). Add a general rule: 'When changing CLI command behavior, grep docs/ for the command name and update all references.'
Validation criteria
The cross-reference guide should be referenced by at least one agent (triage or code) within the next 10 CLI-change PRs. Measure whether documentation-related review findings decrease — target: ≤1 docs-currency finding per initial review for CLI-change PRs, vs the 3 medium findings on the initial review of this PR.
Generated by retro agent from fullsend-ai#5596
What happened
On PR #5596, the code agent and human reviewer spent 5 review iterations discovering that
repos upgradeis documented in 7 distinct locations. The repo's AGENTS.md contains guidance about checking sidebar config when adding new docs, but has no guidance about which existing documentation locations need updating when CLI command behavior changes. The contributing guides cover Go conventions, shell scripting, ADRs, and other topics but include no documentation update guide. Both agents and humans lack a reference for discovering all documentation touchpoints for a given CLI command group.What could go better
A documentation cross-reference — mapping CLI command groups to the files that describe them — would help both agents and human contributors update all locations in one pass. This is a structural gap in the repo: the
reposcommand group is described acrossdocs/cli/repos.md,docs/guides/getting-started/operations.md,docs/guides/dev/cli-internals.md,docs/ADRs/0057-repos-management.md, anddocs/plans/repos-management.md, plus inline CLI help text ininternal/cli/repos.go. Without a cross-reference, contributors must discover these locations by trial and error or review feedback. Confidence is moderate — this would help, but it only works if agents and humans actually consult it. The triage agent change (proposed separately) is the more reliable mechanism since it automates discovery.Proposed change
Add a section to
AGENTS.mdor create a newdocs/contributing/documentation.mdguide that maps CLI command groups to their documentation touchpoints. For thereposcommand group, this would list: (1)docs/cli/repos.md— CLI reference with command table and detailed sections, (2)docs/guides/getting-started/operations.md— operations guide command table, (3)docs/guides/dev/cli-internals.md— CLI reference tree with flags, (4)docs/ADRs/0057-repos-management.md— ADR Decision section (use annotations, not inline edits per ADR conventions), (5)docs/plans/repos-management.md— implementation plan, (6)internal/cli/repos.go— cobra command Short/Long descriptions. Include similar mappings for other major command groups (agent,mint,app, etc.). Add a general rule: 'When changing CLI command behavior, grepdocs/for the command name and update all references.'Validation criteria
The cross-reference guide should be referenced by at least one agent (triage or code) within the next 10 CLI-change PRs. Measure whether documentation-related review findings decrease — target: ≤1 docs-currency finding per initial review for CLI-change PRs, vs the 3 medium findings on the initial review of this PR.
Generated by retro agent from fullsend-ai#5596