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/simulate.ts

View on GitHub
/**
 * An interpreter for `machine.ts`: the statechart executed as data, so a scenario runs against the
 * specification itself rather than against someone's reading of it. It resolves an event the way
 * XState does (the deepest state's own transitions first, then each ancestor's, the first
 * transition in a list whose guard holds), follows a target into a compound state's initial child,
 * and settles a transient state through its `always` list. A transition whose target is the
 * state itself does not re-enter it. It runs no action; it returns the
 * actions a transition names, in order, so a scenario can assert on them.
 *
 * A guard is a name, or names joined by `and` / `or` (`and` binds tighter). A scenario supplies
 * the truth of each name; an unknown name is false, which is the conservative reading.
 */

import { LANES } from './lanes.ts';
import { MACHINE, type StateNode, type Transition, walk } from './machine.ts';

export type Facts = ReadonlySet<string> | ((guard: string) => boolean);

const NODES = new Map<string, StateNode>(walk(MACHINE));

export function holds(guard: string | undefined, facts: Facts): boolean {
  if (!guard) return true;
  const truth = typeof facts === 'function' ? facts : (name: string) => facts.has(name);
  return guard.split(' or ').some((clause) => clause.split(' and ').every((name) => truth(name.trim())));
}

/** The atomic guard names an expression mentions. */
export function atoms(guard: string | undefined): string[] {
  return guard ? guard.split(/ and | or /).map((name) => name.trim()) : [];
}

export type Settled = { state: string; actions: string[]; via: string[] };

export class Leak extends Error {}

/** Follows a target to a resting state: into initial children, and through transient `always` lists. */
export function settle(target: string, facts: Facts, actions: string[] = [], via: string[] = []): Settled {
  const node = NODES.get(target);
  if (!node) throw new Leak(`transition target ${target} is not a state`);
  via.push(target);
  if (via.length > 12) throw new Leak(`settling never rests: ${via.join(' -> ')}`);
  actions.push(...(node.entry ?? []));
  if (node.always) {
    const taken = node.always.find((t) => holds(t.guard, facts));
    if (!taken) throw new Leak(`${target} is transient and no always-transition holds under these facts`);
    actions.push(...(taken.actions ?? []));
    return settle(taken.target, facts, actions, via);
  }
  if (node.states && node.initial) return settle(`${target}.${node.initial}`, facts, actions, via);
  return { state: target, actions, via };
}

/** The transition lists that answer `event` in `state`, deepest first. */
function handlers(state: string, event: string): Array<{ at: string; list: Transition[] }> {
  const out: Array<{ at: string; list: Transition[] }> = [];
  const parts = state.split('.');
  for (let depth = parts.length; depth >= 1; depth--) {
    const at = parts.slice(0, depth).join('.');
    const raw = NODES.get(at)?.on?.[event];
    if (raw) out.push({ at, list: Array.isArray(raw) ? raw : [raw] });
  }
  return out;
}

/** Whether `state` (or an ancestor) answers `event` at all, whatever the facts. */
export function handles(state: string, event: string): boolean {
  return handlers(state, event).length > 0;
}

/**
 * Fires one event. Returns where the card rests, or null when no transition is enabled: the event
 * is dropped and the card stays, which a scenario may or may not accept.
 */
export function fire(state: string, event: string, facts: Facts): Settled | null {
  for (const { list } of handlers(state, event)) {
    const taken = list.find((t) => holds(t.guard, facts));
    if (!taken) continue;
    // A transition to the state the card is already in does not re-enter it (XState v5's
    // default, `reenter: false`): its actions run, its exit and entry actions do not. That is how a
    // lane records something and stays put without starting its own work over.
    if (taken.target === state) return { state, actions: [...(taken.actions ?? [])], via: [state] };
    const exit = NODES.get(state)?.exit ?? [];
    return settle(taken.target, facts, [...exit, ...(taken.actions ?? [])]);
  }
  return null;
}

const KEY_OF = new Map(LANES.map((lane) => [lane.state, lane.key]));
const STATE_OF = new Map(LANES.map((lane) => [lane.key, lane.state]));

export const laneKey = (state: string): string => KEY_OF.get(state) ?? state;
export const laneState = (key: string): string => {
  const state = STATE_OF.get(key);
  if (!state) throw new Error(`no lane ${key}`);
  return state;
};

/**
 * Every lane a card can rest in one event after `from`, under any facts at all: each transition of
 * each handler taken in turn, its target settled under every way its transient states can resolve.
 * This is "is X to Y a legal move", which is what a recorded trace is checked against.
 */
export function successors(from: string, options: { ownEventsOnly?: boolean } = {}): Map<string, string[]> {
  const out = new Map<string, string[]>();
  const add = (state: string, event: string) => out.set(state, [...(out.get(state) ?? []), event]);
  const parts = from.split('.');
  // `ownEventsOnly` stops below the ticket: the lane's events and its phase's. The ticket-wide
  // events (a person's hold, a close, a run start) re-derive the lane from facts and so make nearly
  // any move legal, which is right for a board and useless for checking the moves a driver makes
  // on its own inside one run.
  const floor = options.ownEventsOnly ? 2 : 1;
  for (let depth = parts.length; depth >= floor; depth--) {
    const node = NODES.get(parts.slice(0, depth).join('.'));
    for (const [event, raw] of Object.entries(node?.on ?? {})) {
      for (const t of Array.isArray(raw) ? raw : [raw]) for (const rest of restingStates(t.target)) add(rest, event);
    }
  }
  return out;
}

/** Every resting state a target can settle into, over all facts. */
function restingStates(target: string, seen = new Set<string>()): string[] {
  if (seen.has(target)) return [];
  seen.add(target);
  const node = NODES.get(target);
  if (!node) return [];
  if (node.always) return node.always.flatMap((t) => restingStates(t.target, seen));
  if (node.states && node.initial) return restingStates(`${target}.${node.initial}`, seen);
  return [target];
}

/** A card walking the machine, with the lanes it has rested in and the actions it has run. */
export class Card {
  readonly lanes: string[] = [];
  readonly actions: string[] = [];
  constructor(
    readonly name: string,
    public state: string,
  ) {
    this.lanes.push(laneKey(state));
  }
  /** Fires an event; throws a Leak when nothing answers it, since a scenario only sends events it expects to matter. */
  send(event: string, facts: Facts = new Set()): this {
    const result = fire(this.state, event, facts);
    if (!result) throw new Leak(`${this.name} in ${laneKey(this.state)} dropped ${event}: no transition is enabled`);
    this.state = result.state;
    this.actions.push(...result.actions);
    this.lanes.push(laneKey(result.state));
    return this;
  }
  get lane(): string {
    return laneKey(this.state);
  }
}
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: 470kUpdated 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