From 586fb734f88de0d6b32ae169f68e606b5bc006bd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Canna=C3=B2?= <rene.cannao@gmail.com>
Date: Sun, 22 Mar 2026 10:22:00 +0100
Subject: [PATCH] =?UTF-8?q?Move=20git=20workflow=20to=20top=20of=20task=20?=
 =?UTF-8?q?template=20=E2=80=94=20agents=20skip=20buried=20instructions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Learned from agent post-mortem: agents prioritize technical content over
administrative instructions. Even when branch info is present, agents skim
past it while focusing on code requirements, then use heuristics to fill
the gap they don't realize they have.

Fix: git workflow is now the FIRST section with "do this before reading
anything else" label. Also updates common-mistakes.md with the expanded
root cause analysis.
---
 doc/agents/common-mistakes.md          | 10 ++++++----
 doc/agents/task-assignment-template.md | 10 +++++-----
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/doc/agents/common-mistakes.md b/doc/agents/common-mistakes.md
index 29731dab7..143b87a99 100644
--- a/doc/agents/common-mistakes.md
+++ b/doc/agents/common-mistakes.md
@@ -6,12 +6,14 @@ Patterns observed across multiple AI agent interactions on the ProxySQL codebase
 
 **Symptom:** PR targets `v3.0` (main) instead of the feature branch.
 
-**Root cause:** Agent defaults to the repository's main/default branch when no branch is specified in the issue.
+**Root cause:** Agents prioritize technical content over administrative instructions. Even when branch info is present in the issue, agents often skim past it while focusing on code requirements, then use heuristics (e.g., most recent branch, default branch) to fill the gap they don't realize they have.
+
+**Prevention:** Place git workflow instructions **at the very top** of the issue, before the technical description. Agents read top-down with decreasing attention — administrative details buried after exciting code specs will be skipped.
 
-**Prevention:** Always specify in the issue:
 ```
-Create branch `v3.0-XXXX` from `v3.0-5473`
-PR target: `v3.0-5473`
+### FIRST: Git workflow (do this before reading anything else)
+- Create branch `v3.0-XXXX` from `v3.0-5473`
+- PR target: `v3.0-5473`
 ```
 
 **Detection:** Check `gh pr view <number> --json baseRefName` after PR creation.
diff --git a/doc/agents/task-assignment-template.md b/doc/agents/task-assignment-template.md
index 770b754c8..f9838b26f 100644
--- a/doc/agents/task-assignment-template.md
+++ b/doc/agents/task-assignment-template.md
@@ -13,6 +13,11 @@ Use this template when writing GitHub issues that will be assigned to AI coding
 ```markdown
 ## Task: <one-line description>
 
+### FIRST: Git workflow (do this before reading anything else)
+- Create branch `<branch-name>` from `<base-branch>`
+- PR target: `<target-branch>`
+- If upstream changes needed: `git rebase`, NOT `git merge`
+
 ### Context
 <Why this task exists. Link to parent issue. What problem it solves.>
 
@@ -21,11 +26,6 @@ Use this template when writing GitHub issues that will be assigned to AI coding
 - [ ] New file: `<exact/path/to/file>` — <what it does>
 - [ ] Modified: `<exact/path/to/file>` — <what changes>
 
-### Git workflow
-- Create branch `<branch-name>` from `<base-branch>`
-- PR target: `<target-branch>`
-- If upstream changes needed: `git rebase`, NOT `git merge`
-
 ### Implementation details
 <Describe the approach. Include function signatures, struct definitions,
 or pseudocode. The more concrete, the fewer wrong turns.>