yk-loop

Files (1)

• SKILL.md

SKILL.md (first lines)

# yk-loop: pick, land, pick again

```text
repeat:
  1. PICK    python3 .claude/skills/yk-next/yk_next.py
  2. STOP?   "NOTHING READY", "ERROR: …", or the same item picked a third time without progress → stop,
             report one line
  3. TRIAGE  (issues only) fix, or decision? → /steer classifier: bucket 1–2 → record [steer] + build;
             bucket 3 → comment + hold
  4. LAND    through pairit: a PR resumes at the step its state names; an issue starts at step 0.
             REVIEW EXTERNAL PR / MERGE EXTERNAL PR / RELEASE DUE → .claude/skills/external-pr/SKILL.md
  5. CARRY   a finding that BLOCKS this item is filed and landed first; every other finding is FILED
             (`gh issue create --label bug`), unassigned
  6. goto 1 at once, in this same turn
```

**Before the first pick:** `git checkout -q main && git pull -q`, and make sure the check passes on `main`
(`.venv/bin/python -m pytest -q && .venv/bin/ruff check src/ tests/`). A red `main` is the first item: fix it on a
branch through pairit before anything else. If `.venv` is missing, run
`python3.11 -m venv .venv && .venv/bin/pip install -q -e ".[dev]"`.

**3. Triage.** Land an issue only if it has ONE evident correct outcome: a bug with a repro and an Expected
section, or a small change whose shape the issue already fixes. These are candidates for a hold, not holds by themselves:
- it's a feature that needs a design (a new command, a new workflow, a new theme type, a transport);
- a reasonable maintainer could want two different behaviours, or the fix changes documented behaviour
  someone may rely on;
- it touches the release, versioning or publishing path;
- it would take more than about 400 changed lines, or it can't be tested offline.

For the "someone may rely on" candidate, measure the reliance first with a read-only scan of the fleet repos: no consumer uses it → bucket 1, decide it; a consumer uses it → bucket 3, naming that consumer as the trigger. Before holding anything, run `/steer`'s classifier on it. If a measurement (a read-only fleet scan), the
goals or an existing user ruling settle it — bucket 1 or 2 — decide it: comment `[steer] bucket-N: …` with
the basis, assign it to yourself (`gh issue edit <N> --add-assignee @me`), and build it; list it in your report as open to veto. Hold (`needs-decision`) only a bucket 3
item: one that changes a feature or goal or needs human authority, with that trigger named.

To hold it: post one comment (what you found, the options, the named bucket-3 trigger, your recommended
default, and the question to answer), then `gh issue edit <N> --add-label needs-decision --remove-assignee
@me`, and pick again.

**One item = one context.** This session stays thin. It picks, triages, spawns the test partner (a fresh
`Agent`) and the reviewer (a distinct `claude -p` session), writes the code or delegates it to an
implementer sub-agent, and merges.

**Report through GitHub.** The final stop report lists every bucket-3 hold with its trigger and recommended default (the /steer batched escalation) and every `[steer]` decision as open to veto. The PR, its verdict comment and the closed issue are the record. For each landed
item, give the Captain one line (`#N → PR #P merged: <what changed>`) and keep going.

**One loop per GitHub account.** The picker knows you only by your `gh` login, so a second loop (or a
person) working on the same account would resume the same PRs and issues.

**Never `ScheduleWakeup`, and never end the turn to report between items.** The only wait inside the loop is
`gh pr checks <P> --watch`.

**Don't idle while a sub-agent or reviewer works: pipeline.** While a test partner or a `claude -p` reviewer
runs in the background, claim the next issue with `python3 .claude/skills/yk-next/yk_next.py --skip-prs` and
start it in its own worktree. Plain picking would just answer `RESUME PR … [needs-review]` for the PR under
review. `--skip-prs` goes straight to the claim step with every rule intact (bug first, hold labels,
`depends on`, "an open PR fixes it", the claim-race re-read). Never claim with a bare `gh issue edit`. Two
rules keep it safe:
- Don't run two items that edit the same function at once; hold the second until the first merges.
- A regression you introduced jumps the queue: fix it before new work.

**External PRs (#1195).** A PR whose author is not OWNER/MEMBER/COLLABORATOR follows
`.claude/skills/external-pr/SKILL.md`: the fleet reviews it, merges it with `safe_merge.sh` and cuts the
patch/minor release right after, within the Captain's limits. The picker hands out `REVIEW EXTERNAL PR #N`,
`ESCALATE EXTERNAL PR #N`, `MERGE EXTERNAL PR #N` and `RELEASE DUE`; it only lists `WAIT CAPTAIN #N`
(escalated and labelled `captain-approval`, no `captain-approved`)
and `RELEASE NEEDS CAPTAIN` (a major), and skips a `proposed-reject` PR and one waiting on its author.

**Boundaries.** Never push to `main`, since everything lands by PR (project CLAUDE.md). Never merge another
FLEET member's PR; review it and move on. External PRs follow `external-pr/SKILL.md`: the fleet merges and
releases them within its limits. Never set `captain-approved` (only the Captain does), never close an
external PR (propose it with `proposed-reject`), and never cut a major release.

From Congruentsys/yurtle-kanban, MIT.

More from Congruentsys/yurtle-kanban