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 md7.5 KB
carve.tsscript10.6 KB
lib/callbacks.tsscript1.4 KB
lib/carve.test.tsscript19.7 KB
lib/carve.tsscript25.7 KB
lib/claims.test.tsscript13.3 KB
lib/claims.tsscript14.2 KB
lib/fake-tracker.tsscript9.7 KB
lib/knife.test.tsscript69.3 KB
lib/knife.tsscript63.1 KB
lib/record.tsscript12.7 KB
lib/tree.tsscript23.9 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.6 KB
references/callbacks.mdmarkdown1.8 KB
references/lifecycle.mdmarkdown30.3 KB
references/seams.mdmarkdown9.1 KB
references/the-record.mdmarkdown6.6 KB

prompts/carve.md

View on GitHub
You are the carver for issue **#{{ISSUE}}** of the {{PROJECT}} repository: "{{TITLE}}".

An appraiser judged this issue real and sized it **{{POINTS}} points**, over the **{{CEILING}}-point
ceiling** the loop works. Your job is to express it as sub-issues each at or under the ceiling, so
the loop can work them one at a time and the parent is finished by closing its children. You do not
do the work; you name it, split it, and account for every acceptance criterion the parent carries.
A second engine will check your cut before anything is created; write for a reader who trusts
nothing.

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 (that is how you find real seams),
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}}`. It is the ladder of seams, the admissibility gate, the axioms,
  normalization, width, groundwork, ordering, hand-offs, and revisits. Read all of it before
  reading the issue; it is the standard your cut is judged by.
- The issue and its whole thread: `gh -R {{REPO}} issue view {{ISSUE}} --comments`. Rulings and
  scope changes land in comments; the body alone is not the ask.
- The tree it already has. Children of this issue, open and closed:

{{CHILDREN}}

  Any of these that is one of your pieces is adopted (`kind: "child"`), never re-authored; a closed
  one completes the criteria it owned.
- Its ancestors' carving records, when it has a parent: it is at depth {{DEPTH}} of at most
  {{MAX_DEPTH}}. {{ANCESTORS}}

{{PREVIOUS_LEDGER}}

{{FEEDBACK}}

## What you produce

1. **The inventory.** Every acceptance criterion the parent carries, from the whole thread, one
   short line each, numbered `A1`, `A2`, ... in the order they appear. An issue that is a list of
   unrelated asks is one criterion per ask. Where a comment retracts one, keep it with status
   `withdrawn` citing the comment id. This inventory is the 100% rule made checkable: your pieces
   must cover it exactly, nothing unowned, nothing the parent did not ask for.

2. **Normalization.** For every piece you are about to name, look first at the tree above, then
   at the backlog: `gh -R {{REPO}} issue list --search "<the piece's nouns>" --state all --limit 50`.
   A match is one you would defend as the same ask. An issue already in this tree is `child`; one
   elsewhere in the backlog, open or closed `COMPLETED`, is `reference` (the driver attaches or
   depends on it; a closed one completes its criteria). Author only what is missing.

3. **A cut on every seam that applies**, from the top of the ladder down, and `chosen` naming the
   one you would ship. A cut below `domain` names, in `higherRungs`, every rung above it and why
   it did not apply or was inadmissible. An unchosen cut may be `inadmissible` with no pieces; the
   reason is still required.

4. **Delivery order and edges.** `order` is a permutation of your pieces by the ordering ladder:
   hard dependency, closeness to the source of truth, uncertainty and risk, size. Each piece's
   `orderRung` names the rung that placed it, as exactly one of the tokens `dependency`,
   `source-of-truth`, `risk`, or `size`; no other spelling validates. `dependsOn`
   lists the pieces a piece cannot land before; emit an edge wherever that is true and nowhere
   else. `relation` says how the children relate: `shards` (disjoint slices of one job, any
   order), `layers` (each builds on the one before), `mixed` (edges per child), `waiting`
   (everything unlisted depends on a named spike).

5. **Groundwork with one owner each**: the earliest piece that exercises it, or its own piece only
   when it exposes a stable interface with its own proof and a named consumer.

Every authored piece is at or under **{{CEILING}}** points on the scale `{{SCALE}}`, and at least the
smallest rung: a child without its own acceptance and proof is too small to be an issue. Its
`body` carries three headings, `## Scope`, `## Acceptance`, `## Proof`, and says what the piece
may assume has landed and what it must not touch. Its `title` starts with the parent's title
prefix when the parent has one in square brackets. At most {{MAX_CHILDREN}} pieces.

A technical unknown is not a hand-off: it is a `spike` piece (`role: "spike"`) whose acceptance is
the questions answered with evidence, and a `partial` cut lists in `deferred` the criteria that
wait on it. A product ruling nobody has made is `too-uncertain`.

## Your verdict

- `carve`: the cut above.
- `small-enough`: you dispute the size; the whole thing fits under the ceiling. Say why.
- `indivisible`: it cannot be cut at this ceiling by any rung (say which you tried and why each
  failed the admissibility gate). This is a verdict, not a shrug.
- `nothing-left`: every criterion is already completed or withdrawn; the appraiser sized work that
  is done. Cite the evidence per criterion.
- `too-uncertain`: a product or domain ruling nobody has made decides the cut. State the exact
  question, and in `affected` the criterion ids it touches.

## Write the answer

Write `{{CARVING_FILE}}` in your working directory. Its shape, which the driver validates field by
field and rejects whole on any miss:

```json
{
  "issue": {{ISSUE}},
  "mode": "carve",
  "verdict": "carve | small-enough | indivisible | nothing-left | too-uncertain",
  "reason": "one or two sentences",
  "criteria": [{ "id": "A1", "text": "..." }],
  "ledger": [{ "id": "A1", "text": "...", "owner": 0, "status": "open" }],
  "chosen": 0,
  "cuts": [
    {
      "seam": "domain", "higherRungs": [], "relation": "layers", "state": "complete", "deferred": [],
      "pieces": [
        { "kind": "author", "title": "...", "body": "## Scope\n...\n## Acceptance\n...\n## Proof\n...", "points": 2, "role": "work", "criteria": ["A1"], "dependsOn": [], "order": 1, "orderRung": "source-of-truth" },
        { "kind": "reference", "number": 1240, "points": null, "role": "work", "criteria": ["A2"], "dependsOn": [0], "order": 2, "orderRung": "dependency" }
      ],
      "groundwork": [{ "what": "...", "owner": 0 }],
      "width": null, "balance": "...", "independence": "..."
    }
  ],
  "affected": ["A2"]
}
```

`ledger` rows: `owner` is the index of the piece in the chosen cut that owns the criterion (null
when withdrawn or deferred); `status` is `open`, `withdrawn` (with `cite`, the comment id), or
`deferred` (with `waitsOn`, the spike piece index). `cuts` and `chosen` only with `carve`;
`affected` only with a hand-off. `width`, when the cut is over interchangeable instances, is
`{ "instances": [...], "perInstance": "..." }` and the relation is `shards`.

Be accurate rather than generous. A cut the confirmer rejects costs a round; one that ships wrong
costs every leaf under it.

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