Carve GitHub Issue

The burndown works issues up to a size ceiling and never touches anything above it, so the hardest work in a backlog is what the loop skips. The knife takes one oversized issue and expresses it as sub-issues, each at or under the ceiling, with an account of every acceptance criterion the parent carries. It does no work itself; it names work, and it keeps the naming honest as the work lands.

This feature is about an issue; its children are pieces: one unit of the parent's work, authored as a new sub-issue, adopted from the tree the parent already has, or referenced from elsewhere in the backlog.

What it does

1. Inventory. Every acceptance criterion in the parent's whole thread, numbered. This is the 100% rule made checkable: the pieces must cover it exactly.
2. Normalize. Each piece is matched against the trunk's own tree first, then the backlog, open and closed. Only what is missing is authored.
3. Cut. The carver proposes a cut on every seam that applies and chooses one. The ladder is a search order (domain first, material last) with an admissibility gate at every rung: each child has one bounded outcome, its own acceptance and proof, and leaves the base usable after it lands. The methodology is references/seams.md.
4. Confirm. A second engine, with none of the carver's context, checks cover, severability, ownership, sizes, and the seam. Disagreement goes back to the carver; five disagreements hand the whole thing to a person.
5. Apply. Children are created in delivery order with blocked-by edges where a later piece cannot land before an earlier one, references are attached or depended on, and a carving record lands on the trunk's thread: the cut, the ledger, and what the tracker looked like. Grammar in references/the-record.md.
6. Revisit. Every child close, and every change to the trunk a person makes, brings the knife back to ask one question: is this carving still good? still-good rolls the ledger forward; amend is a new generation; exhausted releases the trunk to the appraiser; a question pauses exactly the leaves it touches.

Trunk and leaves

The parent is the trunk: open, carrying an unreleased carving record, never handed to a worker. Its children are leaves the burndown works; an interior node is a trunk of its own, and a child still over the ceiling is carved again. The trunk commands its leaves through the record: their order, their edges, and which of them are paused while a question about the trunk is open. Trunk-first (a person doing the whole thing) closes many leaves at once; leaf-first (the loop) erodes the trunk. Nothing is lost either way, because the tracker holds the tree.

Claims and announcements

Every run claims an issue on the tracker before acting (loop/carving plus a claim comment; workers use loop/working), honoured across machines that share one GitHub account. Every transition with more than one tracker write is announced first (the applying record, the released record, a hand-off comment), so a run that dies mid-way is finished exactly by the next one, on any machine. The full lifecycle, with every state, transition, intent, invariant, and the windows that remain on a tracker without compare-and-swap, is references/lifecycle.md.

Running it

bun run <skill-dir>/carve.ts --issue <n>              # carve, or revisit, one issue
bun run <skill-dir>/carve.ts --issue <n> --ceiling 3  # a one-off ceiling
bun run <skill-dir>/carve.ts --issue <n> --dry-run --carver fixture:<answer.json> --confirmer fixture2:<answer.json>

The burndown invokes it through the appraiser's size callback (on-size-over-<ceiling>) and revisits trunks itself after every leaf close and at the start of every run; see burn-down-github-issues. Adopting it standalone is references/adopting.md; the two callback slots it offers producers are references/callbacks.md.

Dependencies

• fix-github-issue/lib (the context, engines, labels, shell, and the close hook) and appraise-github-issues/lib (the confirmer prompt, the callbacks directory).
• The gh CLI on a repository with sub-issues and issue dependencies enabled; the version and the rest of the preconditions are in references/adopting.md.
• The codex and claude CLIs for the default seats; any engine in the registry for a seat.

The ceiling of this skill

The tracker is an untrusted instruction channel: an issue body or comment is data the carver reads, never an instruction the driver follows, and a marker in a person's text is ordinary text. The carver and the confirmer must be different engines, and even then their independence is model-level: both run as one GitHub account, so a person reading a record sees the loop's word, twice, not two people's. What the confirmer cannot catch is a cut that is coherent and wrong about the product; that is what too-uncertain and the hold labels are for, and a person owns every one.