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
/**
 * carve-github-issue: express one oversized issue as sub-issues, or re-check a carving.
 *
 * The knife. Given an issue sized over the ceiling, a carver names the parts along the highest
 * natural seam, matches each against the backlog so nothing is authored twice, and a second engine
 * confirms the cut covers the parent before anything is created. Given a trunk that was carved
 * already, it asks whether the carving is still good. Everything it decides lands on the tracker:
 * sub-issues, edges, labels, and a carving record on the trunk's thread. This file is the command;
 * the library it drives is in `lib/`, and the burndown calls `carveIssue` directly.
 *
 * This file is shared: it ships with the skill and is not copied into a repository. Everything
 * true of a repository lives in a config file at that repository's root. Run it from inside the
 * target repository:
 *
 *   bun run <skill-dir>/carve.ts --issue <n>                 # carve, or revisit, one issue
 *   bun run <skill-dir>/carve.ts --issue <n> --dry-run       # with fixture seats: log every write, land nothing
 *   bun run <skill-dir>/carve.ts --issue <n> --ceiling 3     # a one-off ceiling
 *   bun run <skill-dir>/carve.ts --issue <n> --carver codex:gpt-5.6-sol --confirmer claude:claude-opus-5
 *
 * Exit codes: 0 for every confirmed verdict, a resumed generation, or an issue left alone; 1 when
 * the knife failed; 3 when another run holds the issue.
 */

import { existsSync, readFileSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { enrichBlockers } from '../fix-github-issue/lib/blockers.ts';
import { resolveCallbacksDir } from '../appraise-github-issues/lib/appraise.ts';
import { invokeRootFrom, loadProjectConfig, PIPELINE_DEFAULTS, type PipelineKnobs, repoRootFrom } from '../fix-github-issue/lib/config.ts';
import { createContext } from '../fix-github-issue/lib/context.ts';
import { assertDistinctEngines, isFixture, parseSeat, seatLabel } from '../fix-github-issue/lib/engines.ts';
import { ensureLabels } from '../fix-github-issue/lib/labels.ts';
import type { Issue } from '../fix-github-issue/lib/pipeline.ts';
import { log, sh, step, teeConsole } from '../fix-github-issue/lib/shell.ts';
import { ISSUE_LIST_FIELDS } from '../appraise-github-issues/lib/appraise.ts';
import { CARVE_DEFAULTS, type CarveKnobs, JOURNAL_STEPS, type JournalStep } from './lib/carve.ts';
import { carveIssue } from './lib/knife.ts';
import { installStopHandler } from '../fix-github-issue/lib/stop.ts';
import { guardCli } from '../fix-github-issue/lib/cli.ts';
import type { Board } from '../burn-down-github-issues/board.ts';
import { type BoardWriter, waitForBoard, createBoardWriter } from '../burn-down-github-issues/lib/board-writer.ts';

const HERE = dirname(fileURLToPath(import.meta.url));
const PROMPTS = join(HERE, 'prompts');

const args = process.argv.slice(2);

/** Every flag this command reads is named here and in USAGE; a source test holds the three together. */
export const CLI = { flags: ['dry-run'], options: ['issue', 'ceiling', 'carver', 'confirmer', 'fail-after'] } as const;
export const USAGE = `carve-github-issue: carve one oversized issue into sub-issues, or revisit one already carved.
Run it from inside the target repository.

  bun run <skill-dir>/carve.ts --issue <n> [flags]

  --issue <n>             the issue to carve or revisit (required)
  --dry-run               with fixture seats: log every write, land nothing
  --ceiling <n>           a one-off ceiling, in points (default: the config's)
  --carver, --confirmer <seat>
                          engine[:model] for that seat
  --fail-after <step>     testing only: exit hard after that journal step
  --help, -h              print this and exit`;
// Before anything else: an argument this command does not know must never fall through to a real run.
guardCli(args, CLI, USAGE);
const flag = (name: string) => args.includes(`--${name}`);
const opt = (name: string) => {
  const i = args.indexOf(`--${name}`);
  if (i < 0) return undefined;
  const value = args[i + 1];
  if (value === undefined || value.startsWith('--')) {
    console.error(`--${name} needs a value`);
    process.exit(1);
  }
  return value;
};
const positive = (name: string): number | undefined => {
  const raw = opt(name);
  if (raw === undefined) return undefined;
  const parsed = Number(raw);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    console.error(`--${name} expects a positive integer, got '${raw}'`);
    process.exit(1);
  }
  return parsed;
};

const DRY_RUN = flag('dry-run');
const ISSUE_NUMBER = positive('issue');
if (ISSUE_NUMBER === undefined) {
  console.error('usage: bun run carve.ts --issue <n> [--dry-run] [--ceiling <n>] [--carver <seat>] [--confirmer <seat>]');
  process.exit(2);
}
const FAIL_AFTER = (() => {
  const raw = opt('fail-after');
  if (raw === undefined) return undefined;
  if (process.env.CARVE_DEV !== '1') {
    console.error('--fail-after is a development flag; set CARVE_DEV=1 to use it');
    process.exit(1);
  }
  if (!JOURNAL_STEPS.includes(raw as JournalStep)) {
    console.error(`--fail-after expects one of ${JOURNAL_STEPS.join(', ')}, got '${raw}'`);
    process.exit(1);
  }
  return raw as JournalStep;
})();

const REPO_ROOT = repoRootFrom(process.cwd());
const INVOKE_ROOT = invokeRootFrom(process.cwd(), REPO_ROOT);

/** Its own config when the repository has one, the burndown's otherwise. */
const CONFIG_FILE = ['carve-github-issue.config.ts', 'burn-down-github-issues.config.ts'].find((name) => existsSync(join(INVOKE_ROOT, name)));

type Knobs = PipelineKnobs & { maxPoints: number; callbacksDir: string; carve: typeof CARVE_DEFAULTS };

const CONFIG = await loadProjectConfig<Knobs>({
  invokeRoot: INVOKE_ROOT,
  repoRoot: REPO_ROOT,
  fileName: CONFIG_FILE ?? 'carve-github-issue.config.ts',
  defaults: { ...PIPELINE_DEFAULTS, maxPoints: 2, callbacksDir: '<worktreeRoot>/appraisal-callbacks', carve: CARVE_DEFAULTS },
  positiveIntegers: ['maxPoints', 'maxReviewRounds', 'checksTimeoutMinutes', 'smokeTimeoutMinutes', 'maxWorkerAttempts', 'carve.maxDepth', 'carve.maxChildren', 'carve.maxCarveRounds', 'carve.maxCarveAttempts', 'carve.maxGenerations', 'carve.maxRevisitsPerGeneration'],
  blocks: ['carve'],
  help: [
    'The knife is shared across repositories; everything true of a repository lives in that file.',
    'Copy the template from references/adopting.md in this skill (or adopt burn-down-github-issues, whose config this command also reads).',
  ],
});

const SEATS = (() => {
  try {
    const carverSpec = opt('carver') ?? process.env.LOOP_CARVER ?? CONFIG.seats.carver ?? CONFIG.seats.worker;
    const confirmerSpec = opt('confirmer') ?? process.env.LOOP_CARVE_CONFIRMER ?? CONFIG.seats.carveConfirmer ?? CONFIG.seats.confirmer ?? CONFIG.seats.reviewer;
    const seats = {
      carver: parseSeat(carverSpec, '--carver'),
      confirmer: parseSeat(confirmerSpec, '--confirmer'),
      worker: parseSeat(CONFIG.seats.worker, 'seats.worker'),
      reviewer: parseSeat(CONFIG.seats.reviewer, 'seats.reviewer'),
    };
    assertDistinctEngines(seats.carver, seats.confirmer, 'carver and confirmer');
    return seats;
  } catch (error) {
    console.error((error as Error).message);
    process.exit(1);
  }
})();

const ctx = createContext({
  project: CONFIG.project,
  knobs: {
    autoMerge: 'never',
    maxReviewRounds: CONFIG.maxReviewRounds,
    checksTimeoutMinutes: CONFIG.checksTimeoutMinutes,
    agentTimeoutMinutes: CONFIG.agentTimeoutMinutes,
    smokeTimeoutMinutes: CONFIG.smokeTimeoutMinutes,
    pointScale: CONFIG.pointScale,
    maxWorkerAttempts: CONFIG.maxWorkerAttempts,
  },
  seats: { worker: SEATS.worker, reviewer: SEATS.reviewer },
  repoRoot: REPO_ROOT,
  invokeRoot: INVOKE_ROOT,
  promptsDirs: [PROMPTS, join(HERE, '..', 'appraise-github-issues', 'prompts')],
  dryRun: DRY_RUN,
});

const KNOBS: CarveKnobs = {
  ceiling: positive('ceiling') ?? CONFIG.maxPoints,
  ...CONFIG.carve,
  callbacksDir: resolveCallbacksDir(ctx, CONFIG.callbacksDir),
  seats: { carver: SEATS.carver, confirmer: SEATS.confirmer },
  failAfter: FAIL_AFTER,
};

teeConsole(join(ctx.runDir, 'carve.log'));
step(`${ctx.project.name} carve-github-issue`);
log(`run pid ${process.pid} started ${new Date().toISOString()}`);
log(`issue #${ISSUE_NUMBER} | ceiling ${KNOBS.ceiling} | scale ${ctx.knobs.pointScale.join(', ')} | depth up to ${KNOBS.maxDepth} | up to ${KNOBS.maxChildren} children | ${KNOBS.maxCarveRounds} rounds | config ${CONFIG_FILE}`);
log(`carver ${seatLabel(SEATS.carver)} | confirmer ${seatLabel(SEATS.confirmer)} | callbacks ${KNOBS.callbacksDir}`);
if (DRY_RUN) log('DRY RUN: no lock, no claim, no journal file; only fixture seats run; only this log is written');

// Not refused here: finishing an announced generation runs no seat, so a dry run can rehearse a
// resume without one. The knife stops at the first seat it would actually have to run and says so.
if (DRY_RUN && !(isFixture(SEATS.carver) && isFixture(SEATS.confirmer))) {
  log('DRY RUN: no fixture seats, so anything that needs the carver or the confirmer stops there; an announced generation is still rehearsed to its end');
}

let writer: BoardWriter | undefined;
installStopHandler(log, () => waitForBoard(writer));

if (!DRY_RUN) ensureLabels(ctx);

// The knife moves its own cards (C2, C3, C4) when it knows where the board is. A carve started by
// hand, or by a producer's size callback, is otherwise invisible for its whole run: the card sits
// wherever the driver that dispatched it last left it. The pointer is the one card.ts reads.
if (!DRY_RUN) {
  const pointer = join(resolve(REPO_ROOT, CONFIG.project.worktreeRoot, 'runs'), 'board.json');
  try {
    if (existsSync(pointer)) {
      writer = createBoardWriter(JSON.parse(readFileSync(pointer, 'utf8')) as Board, CONFIG.project.repo, log);
      ctx.onLane = (event) => {
        writer?.onLane(event);
      };
      log(`board: moving #${ISSUE_NUMBER}'s card on ${pointer}`);
    }
  } catch (error) {
    // A board is a projection. An unreadable one costs the operator a moving card, never the carve.
    log(`board: ${pointer} could not be read (${(error as Error).message.split('\n')[0]}); carving without it`);
  }
}

const issue: Issue = JSON.parse(sh(ctx, ['gh', 'issue', 'view', String(ISSUE_NUMBER), '--json', ISSUE_LIST_FIELDS]));
enrichBlockers(ctx, [issue]);
const result = await carveIssue(ctx, issue, KNOBS);
log(`${result.outcome}: ${result.reason}${result.generation !== undefined ? ` (generation ${result.generation})` : ''}${result.children?.length ? ` children ${result.children.map((n) => `#${n}`).join(', ')}` : ''}`);
step(result.outcome);
await writer?.settled();
process.exit(result.outcome === 'failed' ? 1 : result.outcome === 'busy' ? 3 : 0);
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