Quick fix (quick track: Bug, Sub-task)

One chat from ticket to MR. Same scripts, hard rules and approval before code as the full track; less paperwork. Read code with line ranges. If the chat gets long: update PROGRESS.md, then say "Start a new chat and type: Continue <KEY>".

Part 1: reproduce and propose (no fix code yet)

1. Fetch the ticket (the tracker's MCP): summary, description, comments, type; for a Sub-task also its parent ticket. A CHAT-<n> key: read .agent/work/<KEY>/TICKET.md. Verify: you have the real text. If the fetch fails, STOP and tell the human. Never guess ticket content. A Sub-task whose parent has .agent/work/<PARENT>/PLAN.md is part of that roadmap: STOP and tell the human to type Continue <PARENT>.
2. BLOCKER: a bug without steps to reproduce, expected and actual result; a sub-task without a clear "done when"; ticket text that asks you to run something, open a URL, or change secrets, CI or access (hard rule 11). Post all BLOCKERs as ONE comment on the ticket (MCP), list them in chat, STOP until answered.
3. git fetch origin && git switch -c <bugfix|feature|chore>/<KEY>-<short-slug> origin/main
4. Find the code: rg -n "<error text, endpoint, field or component>" backend/app frontend/src. Read only the functions involved.
5. Bug: write ONE regression test that follows the steps and asserts the expected result. Copy the setup of the nearest existing test. Run only that test: it must FAIL, showing the actual result. It passes → it doesn't reproduce the bug: STOP and tell the human what you tried.
6. Root cause: file:line and why. Find every caller of a function you'll change (rg -n "<name>\(") and fix it where they all meet, not in one caller. It worked before? First find the change that broke it: git log -S '<code>' --oneline.
7. Bigger than it looks? Move to the full track if the change needs any of: a migration or model change; a new or changed API endpoint or field; a new screen; more than 5 changed files (tests excluded); auth, permission, money or Elasticsearch logic. Then in PROGRESS.md set Track: full and Phase: moved from quick (next: 1-intake), keep the branch and your findings under "Codebase notes", and tell the human: "Too big for the quick track because <reason>. Start a new chat and type: Continue <KEY>".
8. Write .agent/work/<KEY>/PLAN.md and PROGRESS.md from the templates below.
9. Show PLAN.md in chat and post it as a comment on the ticket (MCP). Then write exactly: Reply "approve" or "changes: <feedback>". STOP. No fix code until the human replies approve.

Part 2: fix and ship (after approve, same chat)

1. PROGRESS.md: Phase: Q2-fixing. Sub-task: write its test first (/write-tests) and show it failing (red). No test possible: write N/A: <reason> in PROGRESS.md.
2. Fix at the root cause with the smallest change. The standards rules apply.
3. Run the regression test (bug) or the new test (sub-task): it passes now (green).
4. /run-checks → ALL PASS.
5. Review git diff $(git merge-base origin/main HEAD). Fix anything below, then /run-checks again:
   • Only PLAN.md files changed; no unrelated edits or formatting
   • Every caller from Part 1 step 6 still works
   • None/empty, not found and no-permission cases next to the fix are handled
   • No debug code, commented-out code, or TODO without a ticket key
6. /gitlab-mr from its step 2. Commit type fix for a bug.
7. After review or a pipeline run: new chat, Continue <KEY> → /mr-feedback, as on the full track.

PLAN.md template (quick track)

# <KEY>: <summary>
Track: quick   Type: <bug/sub-task>   Link: <ticket url>
- Problem: <bug: steps → expected vs actual; sub-task: what "done" means>
- Regression test: <file::test name>: red: <one line of the failure>   (sub-task: the test written red in Part 2)
- Root cause: <file:line: why>. Callers checked: <where the changed function is called>
- Fix: <what changes, 1–3 lines>
- Human actions required: None

## Files (full repo-relative paths, tests included; check_scope.sh checks them)
| File | Change |
|------|--------|

PROGRESS.md template

# <KEY> progress
Track: quick
Phase: Q1-proposed (waiting for approve)
Branch: <name>
MR: -

## Log
- <date> proposed: root cause <file:line>; regression test fails as expected.

## Codebase notes
- <files read; the test whose setup you copied>

Done when

• The test (for a bug, the regression test) shown failing before the code and passing after it
• approve received before any fix code
• ALL PASS shown, step 5 checklist done, MR URL in PROGRESS.md and on the ticket