Review agent should cross-reference sibling commands for codebase consistency when reviewing new CLI subcommands

[fullsend-ai-retro]

What happened

On PR #3033, the human Review Squad (waynesun09, 4 agents: Claude x2, Gemini, Codex) caught two codebase-consistency bugs that the fullsend-ai-review bot missed across 13 successful review runs:

1. HIGH: repos install (repos.go:365) used gh.New(token) directly while sibling repos status (repos.go:75) uses newGitHubLiveClient(token) — breaking GITHUB_API_URL support for test and enterprise environments. Every other CLI command in the codebase uses newGitHubLiveClient.
2. MEDIUM: repos install used StringSliceVar for the --repo flag while sibling repos status (repos.go:52) uses StringArrayVar — causing inconsistent comma-splitting behavior between sibling commands.

Both issues are in the same file (repos.go) with the existing repos status command visible in the diff context. The review bot never flagged either pattern despite having access to the full file. Additionally, the bot missed a CRITICAL duplicate repos command registration in root.go (line 51 and 55) that would cause the command to appear twice in help output — a cross-file integration issue introduced when PR #3032 merged while #3033 was in flight.

What could go better

The review agent appears to focus on the new/changed code in isolation without systematically comparing it to sibling patterns in the same file or package. On this PR, two of the most impactful bugs were simple consistency mismatches with code visible in the same file. The AGENTS.md already has strong guidance about forge.Client usage and newGitHubLiveClient, but the review agent didn't cross-reference the existing repos status constructor pattern. A similar gap was observed on the sibling PR #3032 (per #3948), where the review agent spent its budget on low-severity style issues while missing CLI UX pattern violations that human reviewers caught. Confidence: high for the sibling-comparison gap — the evidence is unambiguous across two PRs. Medium confidence on whether AGENTS.md guidance alone will fix it, since the forge abstraction rule already exists but wasn't applied.

Proposed change

Add CLI subcommand review guidance to AGENTS.md (in the 'Go code' section or a new 'CLI commands' subsection). When reviewing a PR that adds a new CLI subcommand to an existing command group (e.g., adding repos install alongside repos status), the review agent should compare the new command's constructor and configuration patterns against sibling commands in the same file. Specific patterns to check:

1. GitHub client construction: all commands in a group should use the same client factory (e.g., newGitHubLiveClient vs gh.New).
2. Flag types: sibling flags with the same semantic (e.g., --repo across install and status) should use the same Cobra flag type (StringArrayVar vs StringSliceVar).
3. Command registration: after adding a new subcommand, verify root.go doesn't register the parent group twice.
4. Testing hook patterns: new commands should follow the same testing override style as siblings.

This also provides evidence for #3948 (CLI UX pattern review guidance).

Validation criteria

On the next 3 PRs that add a new CLI subcommand alongside existing siblings in fullsend-ai/fullsend, the review agent should flag any divergences in client construction, flag types, or registration patterns compared to sibling commands. Baseline: 0/3 such issues caught by the review bot on PR #3033 (two consistency bugs and one duplicate registration missed).

---

Generated by retro agent from #3033

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 2:22 AM UTC · Completed 2:25 AM UTC
Commit: e8381e3 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Feature (review agent guidance)

Problem

The review agent does not cross-reference sibling commands when reviewing new CLI subcommands. On PR #3033, this allowed three consistency bugs to ship undetected across 13 review runs:

1. HIGH: repos install used gh.New(token) instead of newGitHubLiveClient(token) (breaking GITHUB_API_URL support)
2. MEDIUM: repos install used StringSliceVar vs sibling's StringArrayVar for the --repo flag
3. CRITICAL: Duplicate repos command registration in root.go

Root Cause

AGENTS.md lacks explicit guidance for cross-referencing sibling subcommands. The existing forge abstraction rule covers forge.Client usage generally but doesn't instruct the review agent to compare constructor patterns, flag types, and registration against sibling commands in the same group.

Recommended Fix

Add a CLI subcommand review subsection to AGENTS.md with four specific checks:

1. Client construction consistency across command groups
2. Flag type consistency for semantically equivalent flags
3. Command registration deduplication in root.go
4. Testing hook pattern consistency

This is complementary to #3948 (Unix UX patterns) — both could live in the same AGENTS.md section but cover distinct concerns.

Proposed Test Case

Scenario: Review agent detects sibling command divergence
  Given a PR adds a new CLI subcommand to an existing command group
  And the new subcommand uses a different client constructor than its sibling
  When the review agent runs
  Then it should flag the constructor divergence as medium-or-higher severity
  And reference the sibling command's pattern as the expected convention

Validation: Per the issue's criteria, the review agent should catch
sibling divergences on the next 3 CLI subcommand PRs (baseline: 0/3
on PR #3033).

---

Labels: This is a feature request for review agent guidance, specifically targeting the skills/AGENTS.md component. Matches type/feature, agent/review, and component/skills labels. Priority medium based on the evidence — real bugs shipped but the pattern is relatively infrequent (new CLI subcommands).