From 09b005557cc4ad2210659e155541abe07a229315 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 21 Aug 2026 02:27:27 -0400 Subject: [PATCH] chore(agent): add the scheduled backlog-issue prompt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A scheduled pi session reads this file and works one open issue end to end: pick, claim, branch, implement, verify on the tier the change demands, open a PR, stop. It declines rather than improvises where it cannot verify itself — a busy :34115 means another worktree is running the app, and a green e2e run against someone else's build is worse than no run at all. --- .pi/prompts/next-issue.md | 142 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 .pi/prompts/next-issue.md diff --git a/.pi/prompts/next-issue.md b/.pi/prompts/next-issue.md new file mode 100644 index 0000000..ce92017 --- /dev/null +++ b/.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/`). 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 / origin/main +``` + +`` 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":"","base":"main","title":"","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 #`. + +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//jobs` for per-step +status and `GET /api/v1/repos/yonlu/yellowjacket/actions/jobs//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.