What happened
On PR #2360, the code agent implemented ListRepositoryFiles in internal/forge/github/github.go using the Git Trees API (/repos/{owner}/{repo}/git/trees/{sha}?recursive=1). The same endpoint is already used by commitFilesTo in the same file, which handles tree truncation (checking existingTree.Truncated and returning an error, lines 807-813). The code agent's initial implementation did not include truncation handling. The review agent correctly flagged this as a medium-severity finding, and the fix agent addressed it in a follow-up commit by adding ErrTreeTruncated. This single missing pattern required a full fix agent iteration (~22 minutes) and human re-engagement. Related: #2107 (replicate security patterns) and #1289 (read existing implementations) propose similar guidance but for security patterns and dead code respectively — neither specifically covers error/edge-case handling replication across sibling methods.
What could go better
The code agent could have avoided the medium-severity review finding entirely by reading the existing commitFilesTo method before implementing ListRepositoryFiles. Both methods follow the same 4-step pattern (get default branch ref → get commit → get recursive tree → process), and commitFilesTo already handles truncation. The code agent's PR description even mentions that it 'reuses the same refs/commits/trees pattern as CommitFiles,' indicating it was aware of the existing method but did not fully replicate its error handling. Confidence is high that this is a recurring risk: the forge/github package has ~15 methods using the same HTTP client patterns, and new methods that use existing API endpoints will continue to be added. The fix is low-cost (add a paragraph to AGENTS.md) and high-signal (directly prevents a class of medium-severity review findings).
Proposed change
Add guidance to AGENTS.md in the 'Go code' section, after the existing 'Forge abstraction' section:
API pattern replication: When implementing a new method that calls the same API endpoint or uses the same multi-step API pattern as an existing method in the file, read the existing implementation first. Replicate its error handling (e.g., truncation checks, 404-to-ErrNotFound mapping), retry logic (e.g., retryOnTransient, retryOnRepoRace), and response validation. The internal/forge/github/github.go file has several methods that share the Git Trees API pattern (refs → commit → tree) — all should handle truncation consistently.
This complements fullsend-ai#2107 and fullsend-ai#1289 by covering error/edge-case handling specifically, with a concrete example from the forge package.
Validation criteria
Over the next 5 code agent PRs that add new methods to internal/forge/github/github.go or implement new forge.Client interface methods, all should include the same error handling patterns (truncation, retry, error wrapping) as existing methods using the same API endpoint, without requiring a review finding or fix iteration to add them.
Generated by retro agent from fullsend-ai#2360
What happened
On PR #2360, the code agent implemented
ListRepositoryFilesininternal/forge/github/github.gousing the Git Trees API (/repos/{owner}/{repo}/git/trees/{sha}?recursive=1). The same endpoint is already used bycommitFilesToin the same file, which handles tree truncation (checkingexistingTree.Truncatedand returning an error, lines 807-813). The code agent's initial implementation did not include truncation handling. The review agent correctly flagged this as a medium-severity finding, and the fix agent addressed it in a follow-up commit by addingErrTreeTruncated. This single missing pattern required a full fix agent iteration (~22 minutes) and human re-engagement. Related: #2107 (replicate security patterns) and #1289 (read existing implementations) propose similar guidance but for security patterns and dead code respectively — neither specifically covers error/edge-case handling replication across sibling methods.What could go better
The code agent could have avoided the medium-severity review finding entirely by reading the existing
commitFilesTomethod before implementingListRepositoryFiles. Both methods follow the same 4-step pattern (get default branch ref → get commit → get recursive tree → process), andcommitFilesToalready handles truncation. The code agent's PR description even mentions that it 'reuses the same refs/commits/trees pattern as CommitFiles,' indicating it was aware of the existing method but did not fully replicate its error handling. Confidence is high that this is a recurring risk: the forge/github package has ~15 methods using the same HTTP client patterns, and new methods that use existing API endpoints will continue to be added. The fix is low-cost (add a paragraph to AGENTS.md) and high-signal (directly prevents a class of medium-severity review findings).Proposed change
Add guidance to AGENTS.md in the 'Go code' section, after the existing 'Forge abstraction' section:
This complements fullsend-ai#2107 and fullsend-ai#1289 by covering error/edge-case handling specifically, with a concrete example from the forge package.
Validation criteria
Over the next 5 code agent PRs that add new methods to
internal/forge/github/github.goor implement newforge.Clientinterface methods, all should include the same error handling patterns (truncation, retry, error wrapping) as existing methods using the same API endpoint, without requiring a review finding or fix iteration to add them.Generated by retro agent from fullsend-ai#2360