/carve-github-issue

name: carve-github-issue
description: >-
  Break one GitHub issue that is too large to work into sub-issues, unattended, and keep the
  carving honest as the children close. A carver names the pieces along the highest natural seam
  (domain, tier, route, area, file, unit, material), matches each against the backlog so nothing is
  authored twice, and a second engine confirms the cut covers the parent before anything is
  created. The parent becomes a trunk that is finished by closing its children; every child close
  re-checks the trunk, and a trunk with nothing left goes back to the appraiser. Use when the task
  is "this issue is too big, split it", "carve #N into sub-issues", "is this carving still good",
  or when burn-down-github-issues sizes an issue over its ceiling. Requires a per-repository config
  (its own, or the burndown's), the codex and claude CLIs for the default seats, and GitHub
  sub-issues on the repository. Skip for fixing anything; this skill writes only to the tracker.

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` an