Merge pull request 'chore(agent): add the scheduled backlog-issue prompt' (#177) from pi-agent-backlog-automation into main

Reviewed-on: #177

.pi/prompts/next-issue.md

@@ -0,0 +1,142 @@
+---
+description: Take on the next actionable backlog issue end to end, and stop
+---
+Take on exactly one issue from the YellowJacket backlog, end to end, and stop.
+
+Repo: yonlu/yellowjacket at https://git.ljones.me — API base
+https://git.ljones.me/api/v1/repos/yonlu/yellowjacket, auth with
+`-H "Authorization: token $GITEA_TOKEN"`. Default branch is `main`.
+
+## 1. Orient before you pick
+
+Read, in this order: `CLAUDE.md` (the architecture and the reasons behind
+it), `.pi/journal.md` (what happened last), `.planning/NOTES.md` (what was
+already considered and rejected), and `.planning/plans/active/`. Do not skip
+this because the issue looks small — most of this codebase's traps are
+written down in exactly one of those four places, and the ones that bite are
+the ones you didn't read.
+
+## 2. Pick the issue
+
+List open issues. Choose the single highest-value one that is *actionable
+right now*:
+
+- Order by `Priority/Critical` → `High` → `Medium` → `Low`. Within a tier,
+  prefer `Reviewed/Confirmed`, then `Kind/Bug` over `Kind/Enhancement` over
+  `Kind/Feature`.
+- Consult issue #73 (the roadmap) — if it sequences the candidates, that
+  ordering wins over the label ordering.
+- **Skip** anything labelled `Status/Blocked`, `Status/In Progress`,
+  `Status/Abandoned`, `Reviewed/Won't Fix`, `Reviewed/Duplicate`,
+  `Reviewed/Invalid`, or already carrying an open PR.
+- **Skip anything someone else is already on.** The label is not the only
+  claim, because a concurrent session may not have applied it — several pi
+  sessions run against this repo from separate worktrees under
+  `~/.paseo/worktrees/`. Run `git ls-remote --heads origin` and skip any
+  issue whose number or slug matches an existing branch (`60-…`,
+  `fix/<slug>`). A duplicated fix costs more than a skipped issue.
+- **Skip** anything that cannot be verified without hardware you do not
+  have: physical-device Android behaviour (audio output, on-device file
+  writes, real gesture input). A browser at 424px is not a phone — see the
+  Chrome 113 section of `CLAUDE.md`.
+- **Skip** intermittent-failure issues unless you can reproduce the failure
+  on demand within a few minutes. Chasing a 1-in-3 flake is an unbounded
+  task and does not belong in a scheduled run.
+- If nothing qualifies, say so, do nothing, and stop. An empty run is a
+  correct outcome.
+
+## 3. Claim it
+
+Add `Status/In Progress` to the issue and comment that you are picking it
+up. Then branch:
+
+```
+git fetch origin && git checkout -b <type>/<short-slug> origin/main
+```
+
+`<type>` matches the issue's `Kind` (`fix/`, `feat/`, `refactor/`, `test/`,
+`docs/`, `ci/`). Branch from `origin/main`, never by checking out `main`
+itself — this repo is worked from several git worktrees at once and `main`
+is checked out in one of them, so `git checkout main` fails outright.
+
+## 4. Do the work
+
+Fix the issue that was reported and nothing else. Match the surrounding
+code's style. Follow the constraints in `CLAUDE.md` rather than reasoning
+from first principles — where it explains why something is shaped the way it
+is, that shape is load-bearing and there is usually a test pinning it.
+
+**Anything else you discover becomes a new issue, not a bigger diff.** File
+it with the right `Area/`, `Kind/`, `Priority/` labels, describe the
+symptom before the theory, and link it from your PR. Scope creep is the
+failure mode this instruction exists to prevent.
+
+If the work turns out to be materially larger than the issue implied, stop:
+comment on the issue with what you found and what it would actually take,
+remove `Status/In Progress`, push nothing, and end the run.
+
+## 5. Verify — the right tier, not the cheapest one
+
+Run `make generate` if you touched `.sql` or `.templ`, and `make bindings`
+if you changed a bound Go signature. Then run what the change actually
+demands:
+
+- Go change → `make lint` and `make test` (both cover all three build
+  configurations).
+- Frontend component or store → `make ui-test`.
+- User-visible flow → `make e2e` against `make dev-headless`. **Check the
+  port first**: `ss -ltn | grep 34115`. If it is occupied, another worktree
+  is already running the app — do not start a second one and do not run
+  `make e2e`. Attaching to someone else's build produces a green result
+  about code that is not yours, which is worse than no result. Either
+  choose an issue that does not need this tier, or stop and say why.
+- Anything cosmetic or layout-related → look at a screenshot. Several bugs
+  in this repo's history were invisible to every assertion and obvious in an
+  image.
+
+A tier you skipped is a claim you did not check. If a tier fails for reasons
+unrelated to your change, say so explicitly rather than quietly moving on.
+
+## 6. Keep the documentation true
+
+If you changed structure, behaviour, or a constraint, update `CLAUDE.md` in
+the same commit. That file is this project's memory; a change that leaves it
+describing the old shape is worse than no change. Append a short entry to
+`.pi/journal.md` covering what you did, what you verified, and what you left
+open.
+
+## 7. Commit and open the PR
+
+Conventional Commits, imperative subject, ≤72 chars, scope optional. The
+body explains *why*. Push the branch — never push to `main`, never
+force-push.
+
+Open the PR:
+
+```
+curl -sS -X POST \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  https://git.ljones.me/api/v1/repos/yonlu/yellowjacket/pulls \
+  -d '{"head":"<branch>","base":"main","title":"<subject>","body":"<body>"}'
+```
+
+The body states: what the issue was, what you changed and why, **which
+verification tiers you ran and their results**, anything you deliberately
+did not do, and `Closes #<n>`.
+
+Then wait for CI (`ci.yml`, jobs `check` and `e2e`) and report the result on
+the PR. If it fails, read the log — `gitea_ci`'s `job_logs` 404s on this
+Gitea build, so use
+`GET /api/v1/repos/yonlu/yellowjacket/actions/runs/<run>/jobs` for per-step
+status and `GET /api/v1/repos/yonlu/yellowjacket/actions/jobs/<id>/logs` for
+the log — and fix it. Two consecutive failed CI runs on the same cause: stop,
+comment what you know on the PR, and leave it for a human.
+
+**Do not merge.** Comment on the issue linking the PR, leave
+`Status/In Progress` on, and end the run.
+
+## Finally
+
+Report in three lines: which issue you took, what state it is in
+(PR open / CI green / stopped and why), and any issues you filed.