yellowjacket/.pi/prompts/next-issue.md

description

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.