Skip to content

simiancraft/simiancraft-skills / skills/burn-down-github-issues

burn-down-github-issues

Unverified

Run an unattended burndown of a GitHub issue backlog as cards on a per-operator GitHub Projects board whose lanes are an explicit state machine: appraise and size the inbox, carve what is over the ceiling, fix the ready ones in parallel git worktrees, prove each fix on a draft pull request, have an isolated second-engine reviewer judge it, land one branch at a time with freshness checks, and dead-letter per phase whatever a machine cannot finish. Use when the task is "work the backlog unattended", "triage and fix recent issues", "run the issue loop", "burn down issues", or "where is issue N on the board". Requires a per-repository burn-down-github-issues.config.ts at the target repo's root (the loop refuses to start without it), the prove-work-on-github skill, the codex and claude CLIs for the default seats, and a gh token with the project scope for the board. Skip for one-off fixes to a known issue you are already working interactively, and for backlogs whose issues are mostly product decisions rather than code.

FileKindSize
SKILL.mdskill md17.0 KB
board.tsscript6.5 KB
callbacks/README.mdmarkdown1.1 KB
callbacks/on-size-over-ceilingother843 B
card.tsscript4.3 KB
chart-machine.tsscript3.9 KB
claim-race.tsscript6.1 KB
export-machine.tsscript1.8 KB
lanes.tsscript5.2 KB
lib/admission.test.tsscript7.6 KB
lib/admission.tsscript5.5 KB
lib/board-writer.test.tsscript3.6 KB
lib/board-writer.tsscript11.8 KB
lib/carving-revisit.test.tsscript7.5 KB
lib/carving.tsscript26.9 KB
lib/floor/config.test.tsscript456 B
lib/floor/config.tsscript8.1 KB
lib/floor/floor.test.tsscript9.9 KB
lib/floor/floor.tsscript28.7 KB
lib/floor/incident.tsscript11.2 KB
lib/floor/ledger.tsscript5.6 KB
lib/floor/probe.tsscript3.6 KB
lib/lanes.tsscript4.4 KB
lib/machine.test.tsscript11.2 KB
lib/machine.tsscript52.4 KB
lib/place-callbacks.test.tsscript2.5 KB
lib/place-callbacks.tsscript3.0 KB
lib/preflight.test.tsscript4.5 KB
lib/preflight.tsscript1.2 KB
lib/pressure.test.tsscript56.9 KB
lib/refs.test.tsscript1010 B
lib/refs.tsscript1.9 KB
lib/run-scope.test.tsscript5.4 KB
lib/run-scope.tsscript1.2 KB
lib/scenarios.test.tsscript17.1 KB
lib/simulate.test.tsscript7.3 KB
lib/simulate.tsscript7.0 KB
lib/world-sweep.test.tsscript21.4 KB
loop.source.test.tsscript4.8 KB
loop.tsscript66.2 KB
prompts/diagnose.mdmarkdown2.1 KB
prompts/walk.mdmarkdown3.6 KB
references/adopting.mdmarkdown26.3 KB
references/architecture.mdmarkdown20.7 KB
references/floor.mdmarkdown14.6 KB
references/operating.mdmarkdown19.6 KB
references/state-machine.mdmarkdown31.1 KB
status.tsscript4.9 KB
watch.tsscript6.4 KB

lib/floor/ledger.ts

View on GitHub
/**
 * The floor directory: `list.jsonl` in, `ledger.jsonl` out, both append only. This module owns the
 * file names, the two record shapes, the verdict vocabulary, and the reads and writes. The ledger is
 * the floor's memory across runs: what was walked, against which deployed revision, what was
 * found, and the evidence. Nothing here knows about GitHub or agents; see references/floor.md.
 */

import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
import { join } from 'node:path';

export const FILES = {
  list: 'list.jsonl',
  ledger: 'ledger.jsonl',
  evidence: 'evidence',
} as const;

export type ListItem = {
  id: string;
  addedAt: string;
  source: string;
  text: string;
  ref?: { issue?: number; pullRequest?: number; sha?: string; mergedAt?: string; paths?: string[]; unseenBase?: string };
};

export const RUNGS = ['liveness', 'classify', 'look', 'exercise', 'fallback', 'exists-in-git'] as const;
export type Rung = (typeof RUNGS)[number];
/** Rungs an agent may report; the other two belong to the driver. */
export const AGENT_RUNGS: ReadonlySet<Rung> = new Set<Rung>(['look', 'exercise', 'fallback', 'exists-in-git']);

export const VERDICTS = ['present', 'intact', 'not-checkable', 'absent', 'down', 'not-yet-deployed', 'unverified'] as const;
export type Verdict = (typeof VERDICTS)[number];

/** Verdicts that retire an item. Everything else leaves it on the walk list. */
export const TERMINAL: ReadonlySet<Verdict> = new Set<Verdict>(['present', 'intact', 'not-checkable']);
/** Verdicts the agent may write. The pending ones are the driver's to assign. */
export const AGENT_VERDICTS: ReadonlySet<Verdict> = new Set<Verdict>(['present', 'intact', 'not-checkable', 'absent']);
/** Verdicts that mean the environment is wrong and an incident is owed. */
export const REPAIR: ReadonlySet<Verdict> = new Set<Verdict>(['absent', 'down']);

export type LedgerEntry = {
  itemId: string;
  checkedAt: string;
  deployedRevision?: string;
  rung: Rung;
  verdict: Verdict;
  reason: string;
  evidence?: string;
  /** Recorded inside a quiet window, so nothing was paused or run for it. */
  quiet?: true;
};

/** The synthetic item the liveness probe reports against; never on the list. */
export const LIVENESS_ITEM = 'liveness';

function readJsonl<T>(path: string): T[] {
  if (!existsSync(path)) return [];
  const out: T[] = [];
  for (const line of readFileSync(path, 'utf8').split('\n')) {
    const trimmed = line.trim();
    if (!trimmed) continue;
    try {
      out.push(JSON.parse(trimmed) as T);
    } catch {
      // A torn line from a crash mid-write is skipped rather than fatal; the record it would
      // have carried is re-derived on the next walk.
    }
  }
  return out;
}

/**
 * The list, deduplicated on id: the first item with an id wins, so producers append blindly. The
 * one exception is a merge the forge listed before the loop's own record of it arrived: the loop's
 * record knows the issue, so it fills in what the forge's lacked.
 */
export function readList(dir: string): ListItem[] {
  const byId = new Map<string, ListItem>();
  for (const item of readJsonl<ListItem>(join(dir, FILES.list))) {
    if (!item?.id) continue;
    const kept = byId.get(item.id);
    if (!kept) byId.set(item.id, item);
    else if (kept.source === 'forge' && item.source !== 'forge') byId.set(item.id, { ...kept, ...item, ref: { ...kept.ref, ...item.ref } });
  }
  return [...byId.values()];
}

export function readLedger(dir: string): LedgerEntry[] {
  return readJsonl<LedgerEntry>(join(dir, FILES.ledger));
}

/**
 * Appends one JSONL record. A crash mid-write can leave the last line without its newline; a plain
 * append would then fuse the torn fragment and the new record into one invalid line and lose both,
 * so the file is terminated first when it does not end in a newline.
 */
function appendLine(path: string, line: string): void {
  if (existsSync(path)) {
    const size = statSync(path).size;
    if (size > 0) {
      const fd = openSync(path, 'r');
      const last = Buffer.alloc(1);
      try {
        readSync(fd, last, 0, 1, size - 1);
      } finally {
        closeSync(fd);
      }
      if (last[0] !== 0x0a) appendFileSync(path, '\n');
    }
  }
  appendFileSync(path, `${line}\n`);
}

export function appendItem(dir: string, item: ListItem): void {
  mkdirSync(dir, { recursive: true });
  appendLine(join(dir, FILES.list), JSON.stringify(item));
}

export function appendEntry(dir: string, entry: LedgerEntry): void {
  mkdirSync(dir, { recursive: true });
  appendLine(join(dir, FILES.ledger), JSON.stringify(entry));
}

/** The newest ledger entry per item id. */
export function latestByItem(ledger: LedgerEntry[]): Map<string, LedgerEntry> {
  const latest = new Map<string, LedgerEntry>();
  for (const entry of ledger) latest.set(entry.itemId, entry);
  return latest;
}

/** Items with no terminal verdict yet: never walked, still pending, or awaiting repair. */
export function pending(list: ListItem[], ledger: LedgerEntry[]): ListItem[] {
  const latest = latestByItem(ledger);
  return list.filter((item) => {
    const entry = latest.get(item.id);
    return !entry || !TERMINAL.has(entry.verdict);
  });
}

/** The newest liveness entry that found the environment up, if any. */
export function lastClean(ledger: LedgerEntry[]): LedgerEntry | undefined {
  for (let i = ledger.length - 1; i >= 0; i--) {
    const entry = ledger[i];
    if (entry.itemId === LIVENESS_ITEM && entry.verdict === 'intact') return entry;
  }
  return undefined;
}

export function evidenceDir(dir: string): string {
  const path = join(dir, FILES.evidence);
  mkdirSync(path, { recursive: true });
  return path;
}
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: 471kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall