simiancraft/simiancraft-skills / skills/burn-down-github-issues
burn-down-github-issues
UnverifiedRun 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.
references/architecture.md
View on GitHub# Architecture
How and why burn-down-github-issues works: a backlog is a board of cards, each card is in one lane
of an explicit state machine, and polymorphic seats move the cards.
## Shape
The state is the tracker, projected onto a board; the machine is `lib/machine.ts`; the seats are
whatever engine a lane's prompt runs on. Eleven phases, thirty-seven lanes:
```
š Appraisal A1 Inbox ā A2 Appraising ā A3 Confirming close
š¢ Ready B1 Ready
šŖ Carving C1 To carve ā C2 Carving ā C3 Confirming cut ā C4 Spawning children ā C5 Epic ā C6 Revisiting ā C7 Rolling up
šØ Work D1 Coding ā D2 Proving ā D3 Drafted (D4 Sent back, on a rejection)
š Review E1 Ready for review ā E2 Evidence under review
š Landing F1 Approved ā F2 Catching up ā F3 Checks pending ā F4 Smoke ā F5 Merging
ā³ Waits W1 Blocked by sibling, W2 Paused by epic, W3 Claimed elsewhere
ā ļø Dead letters Q1 Appraisal, Q2 Carve, Q3 Work, Q4 Review, Q5 Landing (one queue per machine)
āļø Panel P1 Panel review (before a question parks)
š Human H1 Needs decision, H2 Needs human, H3 Parked
ā
Done T1 Merged, T2 Closed without code, T3 Verified on the floor
```
A run starts by placing every card where its facts say (`references/state-machine.md`,
"Reconcile"), and that placement is the queue: the appraisers take the Inbox, the workers take
Ready, the knife takes To carve and the Epics whose tree moved, and the dead-letter and human
lanes wait for a person. Everything from Coding rightward is the sibling
[`fix-github-issue`](../../fix-github-issue/SKILL.md) skill, which this loop calls once per Ready
card; its [`references/pipeline.md`](../../fix-github-issue/references/pipeline.md) is where the
verdict-file contract, the review budget, the merge boundary, staleness, the resume windows, and
the dead letters it writes are written down. Appraisal is the sibling `appraise-github-issues`
skill and carving is `carve-github-issue`, both run in process. What is loop-shaped stays here:
the board, the placement, the pool, and the run's own durable state.
**One engine implements, another judges.** By default the worker runs on `codex exec` and the
reviewer on `claude -p`; both are seats you can reassign. Splitting the engines is not a preference: a reviewer built from the same
model as the author shares its blind spots by construction, and the merge gate exists precisely to
have blind spots the author does not.
Each role is a seat filled by an `engine:model` spec, resolved against the engine registry in
`fix-github-issue/lib/engines.ts`. The configured defaults are overridable at invocation (one flag
per seat: `--worker`, `--reviewer`, `--confirmer`, `--appraiser`, `--carver`, `--carve-confirmer`,
and `--callback-seat`), so trying a new model is a flag rather than an edit, and supporting a new CLI is one
registry entry rather than a refactor. The driver warns when worker and reviewer resolve to the
same engine, because that configuration gives the merge gate the author's blind spots back.
## The skills this depends on
The loop has two hard dependencies. The first is its sibling
[`fix-github-issue`](../../fix-github-issue/SKILL.md), which owns the worker, the reviewer, and the
pull master, and which the loop imports by relative path; the worker and review prompts live there
too. Skills install one directory at a time, so shared code has to live inside a skill directory
rather than at the collection's root.
The second is [`prove-work-on-github`](../../prove-work-on-github/SKILL.md). Both prompts load it by name: the
worker follows its lifecycle to size, acquire, store, and render proof, and the reviewer judges
with the vision and reasoning modes its `references/judgement.md` defines. The pull master's
staleness rule implements that skill's `references/freshness-and-reproof.md` directly; decay is a
function of distance from the base and of how much of the incoming change intersects the proof's
covered paths, and that reference's covered-paths method is this loop's import-closure walk,
written up there from this implementation.
Install them where each engine can read them. For Claude, the simiancraft-skills plugin carries all
three. For an engine with no skill loader, the prompt's "load the skill" instruction has to
resolve to files on disk, so keep a checkout of the repo readable from the worktrees.
## Boundaries
The loop-level knobs live in `DEFAULTS` at the top of `loop.ts`; every one of them, and everything
repository-shaped, can be set in the repository's `burn-down-github-issues.config.ts`.
| Knob | Default | Meaning |
|---|---|---|
| `seats.appraiser` | `codex:gpt-5.6-sol` | Who sizes; override with `--appraiser engine[:model]` |
| `seats.worker` | `codex:gpt-5.6-sol` | Who implements; override with `--worker engine[:model]` |
| `seats.reviewer` | `claude:claude-opus-5` | Who judges; override with `--reviewer engine[:model]` |
| `ageDays` | 30 | Only issues opened this recently |
| `maxPoints` | 2 | Fibonacci points the loop will attempt |
| `autoMerge` | `code-only` | Merge code; park anything touching data, a migration, a stored string, or CI |
| `maxReviewRounds` | 3 | Review rounds an issue gets, ever, before the DLQ |
| `limit` | 5 | Issues per run |
| `concurrency` | 2 | Issues worked at once, one worktree each |
| `appraiserConcurrency` | 3 | Appraisers at once; no worktree, so they are cheap |
| `appraiseLimit` | 12 | Issues appraised per run |
`maxReviewRounds`, `autoMerge`, and the two seats are the fix skill's knobs; the loop reads them
from the same config file and hands them to the pipeline. What they mean, and the rules that hang
off them (the review budget as a per-issue high-water mark, the dead-letter queue, the difference
between parked and DLQed, and the three accounts the merge boundary unions), is in
[`fix-github-issue/references/pipeline.md`](../../fix-github-issue/references/pipeline.md).
Two boundaries are not knobs, deliberately. The worker never edits production data, and it never
makes a product decision: an issue whose body asks a person to decide, settle, or rule on something
comes back as `needs-decision` with the question stated, however small the diff would have been.
That category is common in most trackers and it is the one place a plausible-looking diff can do
real harm.
## Why worktrees
Every issue gets its own worktree, and that is what lets the loop move on. Work on separate issues
cannot overlap, so a long fix does not block the queue behind it; `concurrency` lanes run at
once and each pulls the next issue as its own finishes. Branches in a single checkout would
serialize the whole thing and let one agent's `git switch` disturb another's tree.
Two things do not follow the work into isolation, and both are handled:
- **The base branch.** Two pull requests landing on the base at the same moment is real
contention, so the merge step queues and happens one at a time.
- **The main checkout.** It is never an agent's working directory; the driver throws rather than
hand it over, because it holds your branch and your uncommitted work.
## Staying current, and when proof goes stale
Every merge moves the base under everything still in flight, and upstream is more correct until a
piece of work is merged: no seat begins on a stale lane, and a lane behind at all merges the base
forward before a revision, a review, or the merge. Whether proof or an approval survives that
catch-up is the separate question the import closure answers. The rule, the closure method, and
the draft-until-complete discipline that keeps a run's CI budget honest all belong to the
pipeline: see
[`fix-github-issue/references/pipeline.md`](../../fix-github-issue/references/pipeline.md).
The loop's own contribution is the `--closure <file>` probe, which prints the import closure of one
entry file so a new adoption can verify its `pathAliases` before any agent runs. A closure of one
module means the aliases resolve nothing, which is the silent failure that degrades staleness to
filename comparison.
## Everything else concurrent lanes contend on
The worktree isolates the working tree. It does not isolate the machine, and each of these is
handled somewhere specific rather than hoped about.
| Contended | Where it is handled |
|---|---|
| Two loop processes claiming the same issues | pid lock in `runs/loop.lock`; a stale lock is reclaimed |
| Shared `.git` index and refs under parallel git | `sh()` retries contention failures with backoff |
| GitHub secondary rate limits | same retry list; a burst of label edits is enough to trigger one |
| A fresh worktree having no `node_modules` | each installs its own; sharing the main checkout's would let the install command write into it |
| Whatever `sharedServices` names | both prompts forbid seeding, resetting, or migrating them |
| Server ports | prompts require a port derived from the issue number |
| The shared evidence branch | prompts forbid force-push and require re-parenting on rejection |
The rule the prompts state plainly: your worktree is yours, and almost nothing else is. An agent
that cannot prove something without mutating shared state is told to return `needs-human` rather
than break another agent's run to get its receipt.
Worktrees are created under the configured `worktreeRoot`, a sibling outside the repository root, so no tool that
walks the working tree has to be told to ignore them. Agent logs land in
`<worktreeRoot>/runs/`, and cleanup collects scratch worktrees an agent leaves behind.
Because lanes interleave, every per-issue line on the console is prefixed with its issue number.
A step that throws (a failed fetch, a rejected push, a merge the retries could not save) fails only
its own lane: the pool logs the error and moves on, and because every durable fact lives on the
issue, the next run picks that issue back up from its labels. A crash costs a lane its progress,
never the run its state.
## The line
A file switch, `<worktreeRoot>/runs/line-switch`, stops the loop at its seams; `operating.md`,
"When the line is paused", lists them once. The pull master's seam, before every merge, is the
fix pipeline's `mayMerge` hook, which the loop answers by waiting until the switch says go; nothing in the pipeline knows a switch exists. The seam holds rather
than parks, because a pause is temporary and a parked pull request needs a human.
The floor runs inside the loop's process, so the switch is its whole interlock with the merge
queue and nothing has to parse a ledger to flip it. Every merge goes up onto the floor through the
pipeline's `afterMerge` hook; a walk of the deployed base that finds something wrong pauses the line
before it files an incident, and releases its own pause once nothing on the floor is wrong. The
incident's fix is the one merge a paused line must not hold, so the floor fixes it under the
loop's context without the `mayMerge` gate. A passing walk is the statechart's `WALKED` event: the
card moves from Merged to Verified on the floor.
A run is done when its merges are verified, not when they land. They reach the floor seconds
before the last lane returns, so the loop drains it under the instance lock: it keeps walking until
every merge has a terminal verdict or is with a person, bounded by `floor.drainMinutes`, and only
then releases the lock. Holding the lock is what keeps a second run from walking the same floor.
## Sizing
Sizing is the sibling `appraise-github-issues` skill, called as a library. What happens after a
size is that skill's callback ladder: the loop writes the size callbacks it ships (`callbacks/`
beside `loop.ts`) into the adopter's callbacks directory on every start, and the appraiser looks
one up per sized issue without knowing what it does. That is the seam for a skill that breaks an
oversized issue apart. Sizing itself is the sibling skill; its prompts, verdicts,
and the second-engine confirmer that must agree before a close are documented there. The loop adds
only selection of the unsized window and the board lines.
The scale is whatever the config's `sizingScale` names (a wiki page, a doc in the repository),
carried on issues by the `size: N` labels. An issue sized above the band, whether by the appraiser
or already on the tracker, is the knife's (see "Carving and revisits"); an unsized issue is sized
by the appraiser, which runs as its own cheap population ahead of the workers.
Where the issue prescribes a remedy that contradicts a written convention (the files
`conventionDocs` names, or what the surrounding code plainly does), the convention wins and the work continues:
the appraiser sizes the remedy the convention implies, and the worker records the divergence in the
pull request. Neither stops for it. A documented convention is a decision already made, so deferring
to it is following that decision rather than making one, and the point ceiling does the stopping
when the convention-respecting fix turns out to be larger.
That rule exists because an issue can prescribe a remedy the repository's own conventions rule
out, and without it every stage executes the prescription faithfully: each judges the diff
against the issue, and nothing judges the issue against the conventions.
## Placement is the queue
The run start computes, for every open issue in the window and every card already on the board,
the lane its facts put it in, in the precedence `references/state-machine.md` gives: closed beats
everything; a merged pull request that owns the issue is Merged; a hold label is its human lane
and a `loop/dlq: <phase>` label its queue; `loop/paused` is a wait; a carved trunk or an issue
with an open child is Epic; an open pull request that owns the issue is Drafted or Ready for
review; a blocker not closed as completed is a wait; a size over the ceiling is To carve, within
it Ready, and none is the Inbox. An issue carrying a live `loop/working` or `loop/carving` claim
is left where it is. With a board, the cards whose lane differs are written; without one, the
placement is still the queue, only unrecorded.
The workers' candidates are the Ready lane, less any issue at its review cap and any the tree
refuses (a pause on an ancestor, an edge in a carving record); a trunk's leaves are worked in the
order its newest carving record gives, grouped where the trunk's newest leaf would have sat, and
the rest of the backlog stays newest-first. The appraisers' candidates are the Inbox, filtered
once more by the appraise skill's own selection so its command and the loop agree. An issue with
a parent is exempt from the age window, since its trunk was selected when it was recent, and so
is any issue already on the board, since the board is what a burndown resumes from. `--only 12,34`
restricts placement, appraisal, selection, resumption, and the sweep to those roots and their
tracker descendants, including children of admitted child trunks, and lifts the age window for
them. Explicitly selected leaves remain selected; unrelated trees remain excluded. Every other
rule still applies, and the console says which lane kept each one out.
`lib/run-scope.ts` retains explicit roots separately from effective membership. Its `refresh`
accepts tracker parent facts, expands membership regardless of response order, and returns only
newly admitted numbers. Repeating the same facts returns none. Every backlog read refreshes the
shared effective set before scope readers use it. Without `--only`, membership stays unrestricted
and refresh returns no incremental admissions.
The work phase is not a fixed list. `lib/admission.ts` is its refill, and `refillingPool`
(`fix-github-issue/lib/pool.ts`) asks it after each lane settles and once more before the run calls
itself idle: the base is fetched, the backlog placed again (which refreshes the scope, so children
the knife carved meanwhile are in it), unsized cards in the window are appraised under
`appraise.lock`, and the Ready cards not yet handed to a worker this run join the pool. So a
dependent whose blocker this run merged, a child carved mid-run, and a trunk's released remainder
are worked in the run that made them eligible. Every admission counts against `--limit` and every
appraisal against `--appraise-limit`; an issue is handed to a worker at most once per run, so a lane
that settles without closing its issue (a busy claim, a failed worker) is not retried until the next
run. A stopping run admits nothing. Changes made outside the run (a person's close, a hold removed,
another run's claim released) are seen by the next refill only if this run is still working.
A trunk's leaves are worked in the order its newest carving record gives, grouped together at the
position the trunk's newest leaf would have had; the rest of the backlog stays newest-first.
Reconciliation closes an open, sized leaf a merged pull request names with a closing keyword
(`fixes #12` at the start of a line or a sentence; a sentence starting with "not" does not count).
It never closes a trunk, a held or paused issue, a claimed issue, or a blocked one, and it re-reads
the issue immediately before closing.
## Carving and revisits
An issue the appraiser sizes over the ceiling is the knife's (the sibling `carve-github-issue`
skill), reached through the size callback the loop renders into the callbacks directory. The knife
turns it into a trunk: sub-issues the loop works as leaves, and a carving record on the trunk's
thread that says their order, their edges, and which are paused.
Every close the loop makes fires the context's close hook: a roll-up comment on the trunk, then a
revisit of the trunk, which asks the knife whether the carving is still good. A trunk is revisited
again in the same run only when its tree's fingerprint moved since the facts the last visit judged
(a child closed, a hold changed), so the close of a trunk's last child rolls it up in the run that
merged it. One call visits a trunk at a time: a trigger that arrives during the visit, including a
close the visit itself makes, is noted and served by one more pass after it, never awaited inside
it. A run caps visits at `MAX_REVISITS_PER_RUN` (`lib/carving.ts`) while the trunk has open
children; the visit after its last child closes is never refused. A revisit
that answers `exhausted` releases the trunk (`loop/released`), and the loop runs the release
appraisal under its own claim: the appraiser sizes the remainder with the closed children in view,
a small remainder becomes a leaf, an oversized one is carved again in process.
At the start of every run, after stranded pull requests are resumed, the sweep reads the open
backlog three times: first every issue carrying a trunk, claim, or pause label (finish an
unfinished announcement, clear a claim whose run died, remove a torn pause, redrive a trunk whose
hold a person removed, revisit a trunk whose fingerprint moved); second every unlabelled issue that
is oversized inside the window or has an open child at any age; third every leaf whose blocker is
closed not planned or gone (its open parent is revisited, else it goes to a person) and every pause
a closed trunk left behind. `--only` restricts all three passes.
## The pool
A seat is an engine running the prompt the card's lane names. The driver's seams are already
polymorphic: the appraisal pool runs the appraiser and confirmer prompts on the Inbox, the knife
runs the carver and cut-confirmer prompts on To carve and on Epics whose tree moved, and the work
pool runs the worker, worker-in-revision, and reviewer prompts on Ready. Past the driver's seams
a Ready card runs from Coding to Merged inside one pipeline call, so Review and Landing are not
yet staffed separately from Work; `references/state-machine.md`, "The agent pool", says what the
finished pool looks like and what remains.
## Known gaps
Proof judgement lives in the sibling proof skill's
[`references/judgement.md`](../../prove-work-on-github/references/judgement.md) and the
covered-paths freshness method in its `references/freshness-and-reproof.md`; the gaps that belong
to the worker, the reviewer, and the pull master (the in-process pull master, the two unrecoverable
resume windows, and the closure walk's blind spots) are listed in
[`fix-github-issue/references/pipeline.md`](../../fix-github-issue/references/pipeline.md). This
file keeps what is loop-shaped.
Appraisal is a judgement made once and recorded as a label, so a wrong size is durable until a
human relabels the issue. The loop re-sizes only what carries no size at all.
Issue bodies and comments are an untrusted instruction channel read by agents whose approval gates
are bypassed; the worktree and read-only contracts are prompts, not sandboxes. The mitigation
today is scope (small sized issues, code-only merges, a second-engine gate) and trust in the
tracker's authors, not enforcement.
Of the five dead-letter queues only the review queue has been exercised end to end (a redrive
that continued a parked pull request to a merge). The others are written; they are not proven.
There is no triage seat yet; every queue waits for a person.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why ā repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" ā or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself ā your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |