/burn-down-github-issues

name: burn-down-github-issues
description: >-
  Run an unattended burndown of a GitHub issue backlog as cards on a per-operator GitHub Projects
  board whose lanes are an explicit state machine: appraise and size the inbox, carve what is over
  the ceiling, fix the ready ones in parallel git worktrees, prove each fix on a draft pull
  request, have an isolated second-engine reviewer judge it, land one branch at a time with
  freshness checks, and dead-letter per phase whatever a machine cannot finish. Use when the task
  is "work the backlog unattended", "triage and fix recent issues", "run the issue loop", "burn
  down issues", or "where is issue N on the board". Requires a per-repository
  burn-down-github-issues.config.ts at the target repo's root (the loop refuses to start without
  it), the prove-work-on-github skill, the codex and claude CLIs for the default seats, and a gh
  token with the project scope for the board. Skip for one-off fixes to a known issue you are
  already working interactively, and for backlogs whose issues are mostly product decisions
  rather than code.

Burn Down GitHub Issues

A burndown is a board. Every issue the loop touches is a card, every card is in exactly one lane (a column of the board; the fix pipeline also calls an issue's worktree its lane), and the lanes are the leaf states of a statechart (`lib/machine.ts`, in XState's vocabulary) that says which seat runs on a card in that lane, what it may decide, and where each decision moves the card. The board is a GitHub Projects board per operator per repository, so a person who starts a burndown comes back to their own board and the loop resumes from it; the console prints the same cards in the same words. The tracker holds the facts (labels, pull requests, claims, records); the board is a projection of those facts that a person can read at a glance, and every run starts by placing every card where its facts say before any seat moves one.

Seats are polymorphic. A seat is an engine running whatever prompt the card's lane calls for (appraiser, close confirmer, carver, cut confirmer, worker, worker in revision, reviewer), then letting go; the card's position is the only input that changes what a seat does. Three rules hold across every seat: the reviewer and the confirmers run on a different engine than the author seats, claims on the issue thread are the lock that keeps two seats off one card, and merging is the one serial lane. `references/state-machine.md` is the machine in prose.

The loop is shared; the repository is config. Nothing in this skill is copied into a repository. Everything true of a repository (remotes, branches, commands, path aliases, invalidation paths) lives in `burn-down-github-issues.config.ts` at that repository's root, and the loop refuses to start without one, naming the missing file and the fields it lacks.

Standards the loop enforces

These travel with the skill because an adopter cannot be assumed to have house rules of its own. The first three are enforced by the driver, so no prompt drift can lose them; the rest are written into the prompts and checked by the reviewer.

• **A failing or unfinished build never merges.** The pull master waits on the pull request's

checks at the last moment before merging and dead-letters the landing instead when they fail or never finish. A green local gate is not a substitute; the checks the pipeline runs are the ones that count.

• **Nothing lands except through a reviewed pull request.** The loop never pushes to the base

branch; the gated merge is the only write it makes there.

• **Upstream is more correct until the work is merged, and no seat begins on a stale lane.** The

base is fetched and merged forward before a fix starts, before proof is captured, before a revision, before a review, and before the merge; what lands is a head that contains everything upstream has. Whether proof or an approval survives a catch-up is decided by whether the base moved into the import closure of the work ("did the world move beneath us"); whether the catch-up happens is not.

• **Pushed history is merged forward, never rebased.** Catch-ups merge the base into the branch,

so nothing another reader has fetched is rewritten.

• **No agent or bot is an author or co-author.** Authorship is for humans; the reviewer hard-blocks

on it.

• **Claims carry receipts.** Proof follows `prove-work-on-github`: pinned, resolvable,

re-checkable by a stranger. Narrative alone never carries a load-bearing claim.

• **Commits and pull requests describe the code, not the process.** Conventional Commits,

imperative, facts only; any mention of agents, prompts, or local tooling is a block.

• **Shared services are never reset or reseeded** to reproduce a claim, and servers bind per-issue

ports; other lanes are reading that state as their own evidence.

Run it

From inside the target repository (any directory of it, including a worktree):

bun run <this-skill-dir>/board.ts                      # once per operator: find or create the board, verify it, record the pointer
bun run <this-skill-dir>/lanes.ts                      # write the 36 lanes and the Phase field onto that board; idempotent
bun run <this-skill-dir>/loop.ts --dry-run             # place every card, print the backlog by lane and what would run; no GitHub or working-tree write
bun run <this-skill-dir>/loop.ts --limit 3             # work three Ready cards
bun run <this-skill-dir>/loop.ts --max-points 5        # raise the size ceiling for this run only
bun run <this-skill-dir>/loop.ts --only 12,34          # restrict the run to these issues, whatever their age
bun run <this-skill-dir>/loop.ts --no-appraise         # skip the inbox; --appraise-limit N caps it instead
bun run <this-skill-dir>/loop.ts --closure <file>      # print the import closure; verifies pathAliases
bun run <this-skill-dir>/loop.ts --worker codex:gpt-5.6-sol --reviewer claude:claude-opus-5
bun run <thi