Merge remote-tracking branch 'origin/main' into 60-context-menu-action-sheet
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user