Move git workflow to top of task template — agents skip buried instructions

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.
pull/5509/head
René Cannaò 2 months ago
parent f7f93e3973
commit 586fb734f8

@ -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.

@ -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.>

Loading…
Cancel
Save