---
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 against real AWS, then carry each through merge → pull → rebuild the linked binary → 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. 'destroy issues' | '#651 #650' | 'provider FPs']"
---

# Work Filed Issues

Take OPEN issues (usually filed by `/hunt-bugs` — deploy/update/destroy bugs, wrong
replacement decisions, missed detection) and drive a few of them to merged,
released, installed 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.

## Launch mode: main checkout, or already inside a worktree

The flow below creates one worktree per lane, which is right when this skill is
launched from the MAIN checkout and wrong when the launch location is ALREADY a
linked worktree (an Orca/ADE workspace, or a session that `cd`-ed into
`.claude/worktrees/<x>`): `git worktree add` then NESTS a worktree inside one,
and deleting the outer workspace takes the inner directory, its uncommitted work
and its git registration with it (go-to-k/cdkd#2390).

**The PARENT computes which case applies BEFORE stage 0**: read
`references/launch-mode.md` and run the probe it holds (the ONLY copy). Before
stage 0 because §2's collision scan already consumes the answer — IN-PLACE its
relative `.claude/worktrees/<w>` paths resolve to nothing and the scan reports
an empty board, which reads as "no competing agents". In the PARENT because
stages 0–3 are delegated to a read-only subagent whose return payload carries
no git state, so an answer computed there never reaches the party that runs
`git worktree add`. State all four printed values — `MODE`, which is
`MAIN-CHECKOUT` or `IN-PLACE`, plus `LANE_TREE`, `MAIN_CHECKOUT` and
`LAUNCH_BRANCH` (the branch §9 puts back; empty if launched detached) — in the
opening report, the first message you write after running the probe and before
any lane starts, and pass them into the triage dispatch and every lane dispatch. That report is their only recorded copy,
and the anchors further down ("STOP unless this is the tree you meant to
adopt") need a comparand.

`IN-PLACE` changes a great deal more than the lane count: the collision scan's
paths, the claim, the branch recipe, the cleanup step, how `main` is reached,
and where the retro branch is created. `references/launch-mode.md` carries the
COMPLETE list as a table mapping each consequence to the stage that fires it —
read it there, and do NOT re-summarise it here. The previous revision of this
paragraph said "changes four things and nothing else" and named four; an
undercount in the always-loaded orchestrator wins over the reference file it
points at, which is the one direction this file must never be wrong in.

## 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 — §5 carries the run
that proved them.

- **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. Hand
  it the probe's four values: §2's worktree
  scan needs the absolute main checkout, and a read-only subagent cannot
  return git state the parent does not already hold. 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) — IN-PLACE too,
  where that branch does not exist yet and is NEVER `LAUNCH_BRANCH`.
- **Lanes (stages 5–8): one general-purpose subagent per claimed issue.**
  Dispatch each with the issue number(s), the posted claim, the stage files to
  read at stage entry (`references/{implement,filing,gates-and-pr,verify}.md`),
  and the probe's `MODE` / `LANE_TREE` / `MAIN_CHECKOUT` / `LAUNCH_BRANCH`. The
  lane creates its own worktree per §5 — or works in place — implements, 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, integ fixtures still needed, anything deferred. Its
  diffs, test logs and review round-trips never enter the parent context.
  A lane must NOT run a real-AWS integ or 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 fixtures and merge while it holds the turn, or run `/run-integ`
  and `gh pr merge` yourself FROM THAT LANE'S WORKTREE (merge gates read the
  worktree the command runs from — §9). Post-merge (pull → rebuild
  → worktree cleanup) 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 |
|---|---|---|
| Before 0. Launch mode | `references/launch-mode.md` | The probe (the ONLY copy), reading its four values, why the parent runs it before stage 0, and the table mapping every IN-PLACE consequence to its stage |
| 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`) |
| 2. Collision landscape | `references/triage.md` | Worktree/branch/PR/ref-recency probes, their clone-locality blind spot, the contested cross-cutting file list (the ONLY copy — `tests/unit/scripts/cross-cutting-list-sync.test.ts` fences it against the gates) |
| 3. Pick file-disjoint issues | `references/triage.md` | Lane count from the launch mode, disjointness gate, freshness quarantine (§3-0), ranking rules (§3-a), naming the next session's verification before writing `next` (§3-b), premise checks against `origin/main` |
| 4. Claim | `references/claim.md` | Claim comment BEFORE first edit, compare-and-swap re-read, tie-break by earliest timestamp, classification-line upgrade + labels on the same edit |
| 5. Implement | `references/implement.md` | One tree per lane, owner probes before adopting one, build before first test, sibling-site sweeps (precondition minus remedy, shape not name, count before/after) |
| 5-f. File what you find | `references/filing.md` | N sites = ONE issue, the dup-check window (mint vs fold into an umbrella), `Severity` / `Effort` as labels, the two `gh issue` gates |
| 6. Gates + PR | `references/gates-and-pr.md` | `/check`, `/check-docs`, marker freshness per worktree, PR create |
| 7. Main advanced | `references/gates-and-pr.md` | Rebase over parallel merges, re-grep what LANDED |
| 8. Verify before merge | `references/verify.md` | `/verify-pr`, `/run-integ`, review tier + reviewer dispatch, live test |
| 9. Ship | `references/ship.md` | Merge → pull → rebuild linked binary → worktree cleanup, owner probes before removing a worktree |
| 10. Retro | `references/retro.md` | Net backlog effect (§10-0), promotion check on this run's `next` filings, where a lesson lands (§10-b/c), ship the retro PR (§10-d) |
| Appendix | `references/gotchas.md` | Gotchas learned the hard way + the existing rules this skill leans on |

## 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**; re-read the claim
  thread before the first edit, before the push, and before opening the PR —
  across clones the issue thread is the ONLY collision signal. (§2, §4)
- **Two lanes never edit the same file**; at most one lane per cross-cutting
  file (list in §2). (§3)
- **Never work in the main checkout** — one tree per lane: a new worktree under
  `.claude/worktrees/<branch>/`, or the launch worktree itself when the mode is
  IN-PLACE. (§5, `references/launch-mode.md`)
- **Real-AWS integ runs and merges are SERIALIZED across lanes** — the parent
  grants the turn, one lane at a time; a lane subagent never starts either on
  its own. Everything else (edits, unit tests, markers, PR create, reviews,
  CI) runs concurrently, because markgate markers are per-worktree. (§9)
- **Verification depth is never traded for cost** (CLAUDE.md → "Cost is not a
  tiebreaker"); ranking decides order, never rigor. (§3-a)
- **English only in every published artifact** — issue bodies/comments, PR
  titles/bodies, commits, code. (CLAUDE.md)
- **The run ends with the retro (stage 10) and the standard wrap report**
  (Remaining work / State / 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/scripts/skill-file-payload.test.ts`, the
mechanical stop on the growth loop that produced the 231 KB predecessor of this
layout; §10-b/§10-c (in `references/retro.md`) govern how to edit, including the
qualified-reference rule `tests/unit/scripts/work-issues-skill-refs.test.ts`
enforces over every `.md` file here.