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 |
prompts/revisit.md
View on GitHubYou are revisiting the carving of issue **#{{ISSUE}}** of the {{PROJECT}} repository: "{{TITLE}}".
This issue is a trunk: it was carved into sub-issues, generation {{GENERATION}}, and something on
the tracker changed since the newest carving record was written ({{TRIGGER}}). You answer one
question: **is this carving still good?** A second engine checks your answer before anything is
written.
You are running headless. Nobody will answer a question, so a question is a verdict, not a pause.
This is a read-only job. Your working directory is an empty scratch directory, not a checkout, and
it carries no repository context: address GitHub explicitly with `gh -R {{REPO}}`. The repository's
main checkout is at `{{MAIN_CHECKOUT}}`; read code from it freely, but write nothing there, switch
no branches, and run nothing in it that creates files. Do not create, edit, label, or comment on
any issue; the driver does every tracker write from your answer.
## Read first
- The methodology: `{{SEAMS_PATH}}`, sections 9 and 10 in particular (hand-offs, spikes, pauses,
revisits).
- The trunk and its whole thread: `gh -R {{REPO}} issue view {{ISSUE}} --comments`. The newest
comment starting `<!-- carve-record` is the record you are revisiting; its JSON block is the
cut, the ledger, and what the tracker looked like when it was written.
- Every child, open and closed, with its thread:
{{CHILDREN}}
- The previous ledger, carried forward for you, with each criterion's status as the driver
re-derived it from the tree just now:
{{PREVIOUS_LEDGER}}
{{FEEDBACK}}
## Your verdict
- `still-good`: the carving stands. Return the inventory and the ledger with every criterion's
current status. Invalid while any criterion is `orphaned` (its owner closed not planned, was
superseded, or is gone), or `deferred` while its spike is closed; those need an `amend`.
- `amend`: a better or necessary cut. Return `cuts` and `chosen` as a carve would, plus
`supersedes`: each child of the current record your cut replaces, with the piece indexes that
replace it and why. A child with work started (a live claim, an open pull request on its
branch, an assignee, a park, a dead letter, a spent attempt or review) is never superseded; adopt it as a piece (`kind: "child"`). Closed children you adopt do not count toward the fan-out ceiling, which bounds only the open and new pieces. A question
answered on the thread may require a rollback piece for work that landed on the old premise.
- `exhausted`: every criterion is `completed` (its owner closed `COMPLETED`) or `withdrawn` (a
comment you cite retracts it), and no recorded dependency is open. The trunk goes back to the
appraiser for whatever remains.
- `indivisible`: what remains cannot be cut at the ceiling by any rung; say which you tried.
- `too-uncertain`: a product or domain ruling nobody has made decides what remains. State the
question, and in `affected` the criterion ids it touches; the leaves that own those, and their
dependents, are paused until a person answers, and the rest keep working.
Criterion ids carry across generations: reuse the previous ledger's id for the same criterion,
and mint a new one only for a criterion that is new to the thread.
## Write the answer
Write `{{CARVING_FILE}}` in your working directory:
```json
{
"issue": {{ISSUE}},
"mode": "revisit",
"verdict": "still-good | amend | exhausted | indivisible | too-uncertain",
"reason": "one or two sentences",
"criteria": [{ "id": "A1", "text": "..." }],
"ledger": [{ "id": "A1", "text": "...", "owner": 0, "status": "completed" }],
"chosen": 0,
"cuts": [ ... as in a carve; only with amend ... ],
"supersedes": [{ "old": 1301, "replacements": [1], "reason": "..." }],
"affected": ["A3"]
}
```
`cuts`, `chosen`, and `supersedes` only with `amend`; `affected` only with a hand-off. Be accurate
rather than generous: a `still-good` that is not costs a leaf its premise.
For every hand-off (`small-enough`, `indivisible`, `nothing-left`, or `too-uncertain`,
where allowed by the mode), include `"affected": ["A1"]` with the criterion ids the question
touches, or `"affected": []` when it touches none. This field is required even for `indivisible`.
Every cut below `domain`, including unchosen cuts, needs one `higherRungs` entry per higher
seam. For example, a tier cut includes:
```json
{ "seam": "tier", "higherRungs": [{ "seam": "domain", "why": "One domain object spans persistence and API; there are no independent domain outcomes." }] }
```
A file cut needs entries for `domain`, `tier`, `route`, and `area`, each with its own `why`.
A partial cut uses criterion ids in `deferred`, and zero-based spike piece indexes in `waitsOn`:
```json
{ "state": "partial", "deferred": [{ "criterion": "A2", "waitsOn": 0 }] }
```
Here piece 0 must have `"role": "spike"`, and the matching ledger row is
`{ "id": "A2", "text": "...", "owner": null, "status": "deferred", "waitsOn": 0 }`.
These fragments illustrate fields within the full answer; they are not standalone answers.
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 | 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: 323k | 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: 323k | 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: 323k | Updated | Claude CodeCodex | Verified | Install |