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, and do not review your own work. Comment on the issue linking the PR, leave Status/In Progress on, and end the run. Whether this merges is decided by a reviewer that did not write it — see below. A CI run is not a review: it proves the tests you wrote pass, which is exactly the thing an author is worst placed to judge.

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.

---

The merge gate

This half is not run by the author. It is run against a PR by someone who has not seen the branch before, and it decides whether the work lands on its own or waits for a human.

A push to main publishes nothing here — release.yml is workflow_dispatch only and all four publishers key on v* tags — so the cost of a wrong merge is a bad commit on main and the time to revert it. That is the whole reason this gate can exist. If that ever changes, this section is void.

Merge only when every one of these is true. Any single no means leave it open.

1. An independent review of the diff returns MERGE or MERGE WITH NITS. CHANGES NEEDED, or a review that could not reach a verdict, means a human looks.
2. CI / check (pull_request) and CI / e2e (pull_request) are success on the PR's current head. Ignore the (push) contexts — they are skipped by design and Gitea folds skipped into a combined state of pending that never clears.
3. The PR is mergeable with no conflicts, rebased onto current main.
4. The diff touches none of: .gitea/workflows/, .releaserc.yml, packaging/, build/, scripts/gitea-release.sh, backend/database/sql/schemas/, backend/database/staleshape*.go, go.mod, go.sum. These either publish to somewhere a mistake cannot be taken back from, or can destroy a database that a user cannot rebuild.
5. The issue is Kind/Bug, Kind/Testing, Kind/Documentation or Kind/Enhancement. A Kind/Feature is a design decision and is never auto-merged, however green it is.
6. The diff is under ~600 changed lines across under ~15 files. Past that, "a reviewer read it" stops being a claim anyone should take on trust.
7. The PR does not claim to have verified something no tier here can see. A change whose evidence would have to come from a physical device is reported, not merged.

When it merges, use {"Do":"merge"} on POST /api/v1/repos/yonlu/yellowjacket/pulls/<n>/merge. Then check the issue actually closed — a squash or an edited merge message drops the Closes footer — and close it by hand with a comment naming the commit if it did not. unclaim.yml strips Status/In Progress on close; if the label is still there a minute later, strip it yourself.

When it does not merge, say so on the PR in one paragraph: which condition failed and what would satisfy it. Leave the PR open, leave the label on, and file the review's substantive findings as issues so they are searchable rather than buried in a PR comment.

A nit is not a blocker, and it is not free either. A MERGE WITH NITS merges, and each nit worth keeping becomes an issue. Do not fix nits on the branch: that is a second author pass with no second review, which is the thing this gate exists to prevent.