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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.9 KB |
| carve.ts | script | 10.6 KB |
| lib/callbacks.ts | script | 1.4 KB |
| lib/carve.test.ts | script | 19.0 KB |
| lib/carve.ts | script | 25.6 KB |
| lib/claims.test.ts | script | 12.9 KB |
| lib/claims.ts | script | 13.8 KB |
| lib/fake-tracker.ts | script | 9.4 KB |
| lib/knife.test.ts | script | 52.3 KB |
| lib/knife.ts | script | 52.9 KB |
| lib/record.ts | script | 12.7 KB |
| lib/tree.ts | script | 23.3 KB |
| lib/validate.test.ts | script | 12.8 KB |
| prompts/carve.md | markdown | 8.1 KB |
| prompts/confirm-carve.md | markdown | 4.1 KB |
| prompts/revisit.md | markdown | 4.9 KB |
| references/adopting.md | markdown | 6.3 KB |
| references/callbacks.md | markdown | 1.7 KB |
| references/lifecycle.md | markdown | 29.7 KB |
| references/seams.md | markdown | 9.1 KB |
| references/the-record.md | markdown | 6.6 KB |
references/the-record.md
View on GitHub# The carving record
The record is the comment the knife posts on a trunk at every step that changes the carving. The newest valid one is authoritative: workers read it before starting a leaf, revisits read it to know what the last carving assumed, and people read the table under it. Everything else on the thread is conversation.
## Grammar
One comment, three parts, in this order:
1. The marker line: `<!-- carve-record gen=N epoch=E state=S -->`, with `S` one of `applying`, `live`, `released`.
2. One fenced `json` block holding the `Record` object verbatim (the shape below).
3. A Markdown table for people, derived from the JSON. Readers parse the JSON only.
A comment is a record only when all three hold: its author is the account the loop runs as, the marker is present, and the JSON parses to the shape and agrees with the marker. A comment failing any of these is logged and treated as not a record. A person cannot forge one by pasting, and the knife's own malformed write is ignored rather than trusted.
## Every marker the collection writes
All are trusted only in a comment (or, for the child marker, an issue body) authored by the loop's account. In a person's text they are ordinary characters. Marker comments by the bot are excluded from the fingerprint, so the knife's own writes never trigger a revisit.
| Marker | Where | Meaning |
|---|---|---|
| `<!-- carve-record gen=N epoch=E state=S -->` | the trunk | a record |
| `<!-- carve-rollup child=N event=E at=T -->` | the trunk | a leaf closed; one per child, event, and close time |
| `<!-- carve-claim kind=K run=R at=T expires=T2 token=X -->` | any issue | a run holds it (`carving` or `working`); the holder renews `expires` in place; `token` is a fresh UUID per claim, so a run that released and claims again finds its new comment and not the old one |
| `<!-- carve-unclaim kind=K run=R -->` | any issue | the claim is released |
| `<!-- carve-handoff verdict=V gen=G -->` | the trunk | the knife handed off; a `json` block carries reason, affected criteria, pause set, both opinions |
| `<!-- appraise-handoff verdict=V -->` | any issue | the appraiser handed off; a `json` block carries the reason |
| `<!-- loop-close verdict=V by=R -->` | any issue | the comment every close posts first; `R` is `appraiser`, `worker`, `knife`, or `reconcile` |
| `<!-- carve-answer issue=N -->` | a spike | the posted answer; never posted twice |
| `<!-- carve parent=N gen=G piece=I -->` | an authored child's body, first line | which trunk, generation, and piece it is |
| `<!-- carve-pause by=N gen=G -->` | a leaf | trunk `N` paused it |
| `<!-- carve-unpause by=N -->` | a leaf | trunk `N` released its pause |
## The JSON shape
```ts
type Record = {
generation: number; // 1 for the first carve; every amend is a new one
epoch: number; // 1; +1 each time a person removes a hold from the trunk
state: 'applying' | 'live' | 'released';
verdict: string; // carve, amend, still-good, exhausted, or a hand-off verdict
reason: string;
cut: Cut | null; // the accepted cut; null on a hand-off with no cut
children: RecordChild[]; // every piece, with its issue number once it exists
supersedes: Array<{ old: number; replacements: number[]; reason: string }>;
affected: string[]; // criterion ids a hand-off's question touches
ledger: Ledger; // every acceptance criterion of the parent
revisits: number; // this generation and epoch
seen: Fingerprint; // what the tracker looked like when this was written
at: string; // ISO time
note?: 'hold-observed'; // a snapshot the sweep wrote while the trunk was held; same state as the record before it
};
```
`RecordChild`: `{ number, piece, kind: 'author' | 'child' | 'reference', link: 'sub-issue' | 'blocker', points, order, orderRung, dependsOn, status, paused, role, title }`. `owner`, `dependsOn`, `waitsOn`, and `replacements` are piece indexes into `children`; `number` is the issue number once it exists (null in an `applying` record for a piece not yet created).
## The ledger
One row per acceptance criterion of the parent: `{ id, text, owner, status, cite?, waitsOn? }`. Ids are stable across generations (`carryIds`: equal or near-equal normalized text keeps its id). Statuses:
| Status | Meaning |
|---|---|
| `open` | not yet done; owned by a piece, or unowned (which only an `amend` may leave) |
| `completed` | its owner closed `COMPLETED` |
| `deferred` | waits on a spike (`waitsOn`); a partial cut lists these |
| `withdrawn` | the thread retracted it (`cite` names the comment); counts as done for exhaustion |
| `orphaned` | its owner closed `NOT_PLANNED`, was superseded and closed, or was deleted; must be re-owned |
Transitions, one row per event:
| Event | Effect |
|---|---|
| a child or reference closed `COMPLETED` | its criteria `completed` |
| closed `NOT_PLANNED`, or deleted | its criteria `orphaned` |
| a completed child reopened | its criteria `open` |
| a superseded child reopened | an unexpected open child; the revisit adopts it or hands off |
| a spike closed | its deferred criteria `open` and unowned; only an `amend` settles them |
| a withdrawing comment removed or edited | the criterion `open` |
| a child's body, title, or comments changed since the record | re-judged by the confirmer at the next revisit |
| supersession | criteria move to the replacement as `open`; `superseded` is a child status, not a criterion status |
`still-good` is invalid while any criterion is `orphaned`, or `deferred` with its spike closed. `exhausted` requires every criterion `completed` or `withdrawn` and no open dependency.
## The fingerprint
What the record saw: the trunk's title, body hash, size, non-loop labels, hold labels, parent, and the people's comments (id and body hash); each child's number, state, reason, title, body hash, labels, blockers, people's comments, and record time; each blocker's number, state, and reason. Arrays are sorted before hashing so two reads of one state compare equal. The sweep compares the current fingerprint with the newest record's `seen` field by field; the first difference names the revisit's trigger. A released record is never compared.
## Readers
- **Workers.** A leaf with a parent reads its parent's newest record, and every ancestor's, before starting: which piece it is, what it may assume has landed (a `layers` relation), what it must not touch (a `shards` relation), and whether it waits on a spike.
- **Revisits.** The knife reads the newest `live` record to answer "is this carving still good", carrying its ledger forward.
- **People.** The table. Nothing in the JSON is needed to understand the state of a trunk.
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: 472k | Updated | Claude CodeCodex | Unverified | 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 |