From bc05aa00402191eb61cc27eec2318e3b7e9e78ce Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Sun, 12 Jul 2026 11:50:15 +0000
Subject: [PATCH] docs(#366): add API pattern replication guidance to AGENTS.md

Instruct code agents to read existing sibling methods before
implementing new methods that call the same API endpoint or use
the same multi-step API pattern. Covers replicating error handling
(truncation checks, 404-to-ErrNotFound mapping), retry logic
(retryOnTransient), and response validation.

Prevents a class of medium-severity review findings where new
methods omit error handling that existing methods already
implement for the same endpoint.

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

diff --git a/AGENTS.md b/AGENTS.md
index 5620b735fd..36bd348da1 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`), and response validation. In `internal/forge/github/github.go`, `commitFilesTo` implements the Git Trees API pattern (refs → commit → tree) with truncation checks — any new method using the same endpoint must 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.