docs(#6424): add Timeout() / context.DeadlineExceeded pitfall to Go guidelines

[fullsend-ai-coder]

Summary

Adds a "Go pitfalls" section to docs/contributing/go-code.md documenting that context.DeadlineExceeded implements interface{ Timeout() bool } (returning true), so timeout detection via interface assertion must guard against context errors first. Without the guard, context deadline errors are incorrectly classified as transient and retried.

Related Issue

Closes #6424

Changes

• Added new "Go pitfalls" section after "Error handling and naming conventions" in docs/contributing/go-code.md
• Documented the Timeout() bool / context.DeadlineExceeded interface trap with WRONG and CORRECT code examples
• Explained why context deadline/cancellation errors should never be retried
• Referenced forge.IsTransient as the canonical correct pattern
• Added review guideline for flagging unguarded Timeout() checks as medium-severity findings
• Follows the pitfall documentation pattern from cel-triggers.md and shell-scripting.md

Testing

• Documentation-only change — no Go production code modified
• No tests required (no behavioral changes)
• gitlint passes on commit message

---

Closes #6424

Post-script verification

• Branch is not main/master (agent/6424-go-timeout-pitfall)
• Secret scan passed (gitleaks — b294e1eaab74f8174dda7c556cad7e0508f6d9eb..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:02 PM UTC · Completed 6:10 PM UTC

Commit: f9df829 · View workflow run →

[github-actions]

Site preview

Preview: https://896f39bb-site.fullsend-ai.workers.dev

Commit: f9df82999b550c95d21c42b8436d9f7d4c5c109f

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Looks good to me

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 12:18 PM UTC · Completed 12:26 PM UTC

Commit: f9df829 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Cost: $1.36

[fullsend-ai-retro]

Retro: PR #6427 — Go Timeout pitfall documentation

This PR documents the Timeout() bool / context.DeadlineExceeded interface trap in docs/contributing/go-code.md. It was generated end-to-end by the agent pipeline: a retro agent finding from PR #6217 → issue #6424 → triage → code → review → human merge.

Timeline

Time (UTC)	Event
Aug 20, 17:48	Retro agent files #6424 from PR #6217 analysis
Aug 20, 17:50–17:53	Triage agent runs (~3 min): labels documentation, go, priority/medium, ready-to-code
Aug 20, 17:55–18:00	Code agent runs (~5 min): single commit, +34 lines to go-code.md
Aug 20, 18:00	PR created, ready-for-review label applied
Aug 20, 18:02–18:10	Review agent runs (~8 min): 3 sub-agents (correctness, style-conventions, intent-coherence), zero findings, APPROVED
Aug 26, 12:15	Human reviewer approves (6 days later)
Aug 26, 12:16	Merged via merge queue

Assessment

This workflow went well. The retro→triage→code→review pipeline completed in ~22 minutes with zero rework. The code agent produced technically accurate documentation on the first attempt, following existing pitfall patterns from cel-triggers.md and shell-scripting.md. The review agent's three sub-agents correctly verified the Go code examples, documentation structure consistency, and scope alignment with issue #6424. The human reviewer approved without additional comments — zero delta between agent and human review.

Evidence for existing issues (no new proposals needed)

• #6210 (Define criteria for enabling review agent automated code approvals): This PR sat 6 days waiting for human review. The review agent's approval was correct and complete — human review was confirmatory, not additive. This is another data point supporting docs-only PRs as a candidate category for graduated autonomy, alongside the evidence already tracked in #5289.
• #5319 (Retro dispatch should detect retro-originated PR chains): This retro is analyzing a PR that was itself generated from a retro finding. The chain is: PR ci(#6216): retry transient errors in after-scenario cleanup hooks #6217 → retro → issue Document Timeout() interface / context.DeadlineExceeded pitfall in Go coding guidelines #6424 → PR docs(#6424): add Timeout() / context.DeadlineExceeded pitfall to Go guidelines #6427 → retro (this run). In this case the retro produces an "all clear" result rather than harmful cascading proposals, but the compute is still spent on a self-referential analysis.
• #5514 (Add confidence annotation to review verdicts): The review agent ran 3 sub-agents with zero findings but its public comment was just "Looks good to me" with no confidence or scope metadata. Confidence annotations would help graduated approval decisions for clean docs PRs like this one.