From bd2724179fc0bc355f2bbc6d399e7479206cd2f5 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Fri, 10 Jul 2026 12:48:44 +0000
Subject: [PATCH 1/2] docs(#243): add API pattern replication guidance to
 AGENTS.md

Add a new section after "Forge abstraction" in the Go code
guidance. When implementing a method that calls the same API
endpoint as an existing method, read the existing implementation
first and replicate its error handling, retry logic, and
response validation. Uses the Git Trees API truncation pattern
as a concrete example.

This prevents review findings like the one on upstream PR #2360,
where a missing truncation check required a full fix iteration.

Closes #243
---
 AGENTS.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 5620b735f..905a2624c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -62,6 +62,10 @@ All git forge operations (GitHub API calls, PR comments, issue creation, workflo
 
 **When reviewing PRs:** Flag any direct `exec.Command("gh", ...)`, raw GitHub API calls, or other forge-specific operations outside `internal/forge/github/` as a medium-severity or higher finding. This is an architectural violation, not a style preference.
 
+## 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.
+
 ## Architecture Decision Records (ADRs)
 
 These rules apply whenever you touch `docs/ADRs/` or review a PR that does. Full authoring guidance is in [`skills/writing-adrs/SKILL.md`](skills/writing-adrs/SKILL.md); invoke that skill when writing a new ADR.

From 978e416068bc79ecdf28b011eaca6dc89edfcc0a Mon Sep 17 00:00:00 2001
From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Fri, 10 Jul 2026 17:43:31 +0000
Subject: [PATCH 2/2] fix(#243): address review feedback on PR #264

- Remove nonexistent retryOnRepoRace from examples
  (only retryOnTransient exists)
- Fix "several methods" claim: name commitFilesTo as
  the centralized implementation
- Add bold lead-in for visual consistency with
  adjacent Forge section

Addresses review feedback on #264
---
 AGENTS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 905a2624c..7b9c53a53 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,7 +64,7 @@ All git forge operations (GitHub API calls, PR comments, issue creation, workflo
 
 ## 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.
+**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`), and response validation. The `internal/forge/github/github.go` file has the Git Trees API pattern (refs → commit → tree) currently centralized in `commitFilesTo` — new methods using the same endpoint should replicate its truncation handling.
 
 ## Architecture Decision Records (ADRs)