work-issues

name	work-issues
description	Work through already-filed GitHub issues (typically the bug-hunt's output) end to end — triage safely, pick a few FILE-DISJOINT issues to fix in parallel, claim each on the issue before starting (collision-safe with other agents), verify, then carry each through merge (via /merge-pr) → pull → worktree cleanup. Use when asked to "handle/address filed issues", not to hunt for new bugs (that is /hunt-bugs).
argument-hint	[optional focus, e.g. 'start-alb issues' | '#231 #234' | 'cloudfront FPs']

Work Filed Issues

Take OPEN issues (usually filed by /hunt-bugs — wrong routing, missing env injection, container-boot gaps, reload misbehavior) and drive a few of them to merged fixes. The differentiator of this skill over just "fix issue #N" is safe, collision-free PARALLELISM: when there is a backlog and other agents/sessions are running, pick issues that cannot step on each other, announce which ones you took, and only then start.

The golden rule: decide the set FIRST, claim it on the issues, THEN edit. The issue comment is the lock — it is what stops two agents from fixing the same thing and colliding on the same file. The run does not end at the last merge: the retro stage folds what this run taught you back into this skill's files, while the evidence still exists.

How this skill is packaged (read this before stage 0)

This file is a thin orchestrator. The full procedure lives in per-stage files under references/, split so a run loads only the stage it is in instead of the whole corpus. Reading the stage file at stage entry is MANDATORY, not optional — each file carries hard rules and measured failure modes without which the stage summary below is not executable. A bare §N anywhere in this skill points into the file that holds that section (map in the table).

Delegate for context; keep the locks and the serialization in the parent. The placements below are live-proven, not aspirational: on 2026-08-28 this repo's own skill-split PR (go-to-k/cdk-local#621) was built END-TO-END by a lane subagent — worktree, implementation, gates, reviewer dispatch, CI — with the parent doing only claims, serialized merges and cleanup, and every hook and markgate gate fired inside the lane's tool calls exactly as in the parent (the sibling go-to-k/cdk-real-drift#1831 shipped the same way the same day).

• Triage (stages 0–3): a read-only subagent (general-purpose or Explore) whose prompt is: read references/triage.md in full, execute it against this repo, and return ONLY the candidate table — per issue: number, title, target files, rank + the rule that decided it, collision evidence (worktrees / branches / claims found), and any premise-check findings. The raw backlog listing and issue bodies stay out of the parent context.
• Claim (stage 4): the PARENT, never a subagent — the claim is the lock, so it names the session accountable for the lane; it also names the lane branch/worktree the dispatched subagent will create (§4).
• Lanes (stages 5–8): one general-purpose subagent per claimed issue. Dispatch each with the issue number(s), the posted claim, and the stage files to read at stage entry (references/{implement,gates-and-pr,verify}.md). The lane creates its own worktree per §5, implements (unit + fixture coverage in the SAME PR, per the never-defer-the-integ invariant), runs /check + /check-docs, opens the PR, dispatches its review tier (a lane may spawn reviewer subagents), addresses findings, and drives CI to green — then STOPS at merge-ready and reports back: PR number, HEAD sha, markers set, review verdicts, the integ fixture(s) its diff needs, anything deferred. Its diffs, test logs and review round-trips never enter the parent context. A lane must NOT start a Docker-side integ run (/run-integ, or the /create-integ run a new-factory PR needs before gh pr create — it asks the parent for that turn mid-lane) or a merge on its own — that is the serialization invariant below, not a capability gap.
• Finishing (stage 9): the parent, one lane at a time. Grant each merge-ready lane its turn — resume the lane agent (SendMessage) to run its named integ fixture(s) and /merge-pr while it holds the turn, or run /run-integ and /merge-pr yourself FROM THAT LANE'S WORKTREE (markgate markers are per-worktree, so the integ marker must land in the tree the merge is judged from — §9). Post-merge (pull → worktree/branch audit) follows §9.
• Retro (stage 10): a subagent, dispatched after the last merge with references/retro.md plus this run's key evidence (what you re-read, what the text sent you into, corrections the user made) to measure the backlog effect, draft the skill edits, and ship them as the retro PR.

Running a lane in the parent instead stays legal (a single-lane run, or a lane the user wants to watch); the stage files apply unchanged either way.

Stages

Stage	File (read at entry)	What it covers
0. Safety screen	references/triage.md	Untrusted issues/comments: author_association via REST, never download/run third-party content, defer engage/minimize/block to the maintainer
1. List backlog	references/triage.md	REST listing (PR filter, per_page=100, created_at), volume assessment
2. Collision landscape	references/triage.md	Worktree/branch/PR/ref-recency probes, their pre-first-write blind spot (before a lane's first write, only its §4 claim comment can see it), the shared cross-cutting runtime modules at most one lane may own
3. Pick file-disjoint issues	references/triage.md	Disjointness gate, ranking rules, premise checks against origin/main, and §3-a: a FRESH issue belongs to the lane that FILED it (60-minute window)
4. Claim	references/claim.md	Claim comment BEFORE first edit (English only, like every issue this run files), claim what you FILE too, re-check for a competing claim right before you start
5. Implement	references/implement.md	One worktree per lane, build before first test, sibling-site sweeps, unit + integ in the SAME PR
6. Gates + PR	references/gates-and-pr.md	Gate liveness probe before the session's first commit, vp run verify, /check + /check-docs markers, PR create with Closes #<n>
7. Main advanced	references/gates-and-pr.md	Rebase over parallel merges, re-grep what LANDED, run a peer's new repo-wide check over your diff
8. Verify before merge	references/verify.md	/verify-pr, /run-integ, review tier + reviewer dispatch, live test, §8-z: what a no-discrimination mutation probe actually means
9. Ship	references/ship.md	/merge-pr (never a hand-run merge) → pull → worktree cleanup, owner probes before removing a worktree

Hard invariants (hold even between stage reads)

• Safety first: never download, unpack, run, apply, or install anything a non-maintainer attached or linked — any vector (zip / patch / package / curl | sh) is the same play. Read bodies via gh api only. (§0)
• Claim before the first edit, on every issue you take — and claim what you FILE when this run means to pick it up; re-check for a competing claim right before you start. Before a lane's first write, the claim comment is the ONLY artifact that proves the lane exists. (§2, §4)
• Two lanes never edit the same file; at most one lane per shared cross-cutting runtime module (list in §2). (§3)
• Never work in the main checkout — one worktree per lane under .claude/worktrees/<branch>/. (§5)
• Never defer the integ: a src/** fix ships its Docker/fixture coverage in the SAME PR — the integ gate enforces it at merge time. (§5, §8)
• Merge only via /merge-pr — a hand-run gh pr merge from a side worktree is gate-blocked and trips the worktree fatal besides. (§9)
• Docker-side integ runs and merges are SERIALIZED across lanes — the parent grants the turn, one lane at a time; a lane subagent never starts /run-integ, /create-integ, or /merge-pr on its own (the flow runs the integ in §8 and the merge in §9). Everything else (edits, unit tests, markers, PR create, reviews, CI) runs concurrently, because markgate markers are per-worktree (.claude/rules/hooks.md) — while the Docker daemon is shared host state. (§8, §9)
• English only in every published artifact — issue bodies/comments, PR titles/bodies, commits, code. (.claude/CLAUDE.md)
• The run ends with the retro (stage 10) and the standard wrap report (Remaining work / Session close), unprompted.

Where lessons land (keeps this file thin)

The retro amends the STAGE FILE the lesson belongs to — references/<stage>.md — never this orchestrator, unless the stage list itself changed. This file's byte size is capped by tests/unit/skills/skill-file-payload.test.ts; the cap is the mechanical stop on the growth loop that produced the 120 KB predecessor of this layout. §10-b/§10-c (in references/retro.md) govern how to edit: amend in place, escalate a twice-violated sentence to a test or hook, qualify every cross-repo issue reference (go-to-k/cdk-local#N, never bare #N — this directory is mirrored into the sibling repos and tests/unit/skills/work-issues-skill-refs.test.ts enforces it over every mirrored .md file, the ones here included).