simiancraft/simiancraft-skills / skills/carve-github-issue
carve-github-issue
VerifiedBreak 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
- Inventory. Every acceptance criterion in the parent's whole thread, numbered. This is the 100% rule made checkable: the pieces must cover it exactly.
- Normalize. Each piece is matched against the trunk's own tree first, then the backlog, open and closed. Only what is missing is authored.
- 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. - 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.
- Apply. Children are created in delivery order with
blocked-byedges 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 inreferences/the-record.md. - 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-goodrolls the ledger forward;amendis a new generation;exhaustedreleases 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) andappraise-github-issues/lib(the confirmer prompt, the callbacks directory).- The
ghCLI on a repository with sub-issues and issue dependencies enabled; the version and the rest of the preconditions are inreferences/adopting.md. - The
codexandclaudeCLIs 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.
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: 469k | 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: 321k | 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: 321k | 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: 321k | Updated | Claude CodeCodex | Verified | Install |