Skip to content

simiancraft/simiancraft-skills / skills/carve-github-issue

carve-github-issue

Verified

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.

FileKindSize
SKILL.mdskill md5.9 KB
carve.tsscript10.6 KB
lib/callbacks.tsscript1.4 KB
lib/carve.test.tsscript19.0 KB
lib/carve.tsscript25.6 KB
lib/claims.test.tsscript12.9 KB
lib/claims.tsscript13.8 KB
lib/fake-tracker.tsscript9.4 KB
lib/knife.test.tsscript52.3 KB
lib/knife.tsscript52.9 KB
lib/record.tsscript12.7 KB
lib/tree.tsscript23.3 KB
lib/validate.test.tsscript12.8 KB
prompts/carve.mdmarkdown8.1 KB
prompts/confirm-carve.mdmarkdown4.1 KB
prompts/revisit.mdmarkdown4.9 KB
references/adopting.mdmarkdown6.3 KB
references/callbacks.mdmarkdown1.7 KB
references/lifecycle.mdmarkdown29.7 KB
references/seams.mdmarkdown9.1 KB
references/the-record.mdmarkdown6.6 KB

prompts/revisit.md

View on GitHub
You 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.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall