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/machine.test.ts

View on GitHub
import { describe, expect, it } from 'bun:test';
import { LANES } from './lanes.ts';
import { MACHINE, transitions, walk } from './machine.ts';

const states = new Map(walk());

describe('the machine and the lane table agree', () => {
  it('every lane key is unique across the machine, and no two lanes share a name', () => {
    const keys = LANES.map((l) => l.key);
    expect(new Set(keys).size).toBe(keys.length);
    const names = LANES.map((l) => l.name);
    expect(new Set(names).size).toBe(names.length);
    expect(LANES.length).toBe(37);
  });

  it('every lane is exactly one leaf state', () => {
    const byLane = new Map<string, string[]>();
    for (const [path, node] of states) {
      if (!node.lane) continue;
      byLane.set(node.lane.key, [...(byLane.get(node.lane.key) ?? []), path]);
    }
    for (const lane of LANES) {
      expect(byLane.get(lane.key) ?? [], `lane ${lane.key} ${lane.name}`).toHaveLength(1);
    }
    for (const [lane, paths] of byLane) {
      expect(LANES.some((l) => l.key === lane), `state ${paths.join(', ')} names unknown lane ${lane}`).toBe(true);
    }
  });

  it('every leaf state under ticket is a lane, unless it is transient, history, or final', () => {
    for (const [path, node] of states) {
      if (!path.startsWith('ticket.')) continue;
      const leaf = !node.states || Object.keys(node.states).length === 0;
      if (!leaf) continue;
      if (node.type === 'transient' || node.type === 'history' || node.type === 'final') continue;
      expect(node.lane, `leaf ${path} has no lane`).toBeDefined();
    }
  });

  it('every transition target resolves to a state', () => {
    for (const { from, event, transition } of transitions()) {
      expect(states.has(transition.target), `${from} on ${event} targets ${transition.target}`).toBe(true);
    }
  });

  it('every lane state has a way out', () => {
    for (const [path, node] of states) {
      if (!node.lane) continue;
      expect(Object.keys(node.on ?? {}).length, `${path} has no transitions of its own`).toBeGreaterThan(0);
    }
  });

  it('every lane state is reachable from some transition or is the initial state of its phase', () => {
    const targets = new Set(transitions().map((t) => t.transition.target));
    for (const [path, node] of states) {
      if (!node.lane) continue;
      const parent = path.slice(0, path.lastIndexOf('.'));
      const initial = states.get(parent)?.initial;
      const isInitial = initial !== undefined && `${parent}.${initial}` === path;
      expect(targets.has(path) || isInitial, `${path} is never entered`).toBe(true);
    }
  });

  it('a guarded list ends in an unguarded fallback or the guards are exhaustive by construction', () => {
    // Every multi-transition list must end with an unguarded transition, so no event can fall
    // through silently. The one exception is APPRAISED, whose verdicts are a closed set the
    // pipeline already rejects outside of.
    for (const [path, node] of states) {
      for (const [event, list] of Object.entries(node.on ?? {})) {
        if (!Array.isArray(list) || event === 'APPRAISED' || event === 'KNIFE_VERDICT' || event === 'WORKER_VERDICT' || event === 'HOLD_ADDED_BY_PERSON') continue;
        expect(list[list.length - 1].guard, `${path} on ${event} can fall through`).toBeUndefined();
      }
    }
  });

  it('every lane can reach a terminal lane or a human lane, treating guards as optimistic edges', () => {
    // crucible's "cannot reach final" and SPIN's invalid end state; a guard only removes an edge at
    // run time, so a target reachable here is reachable in some run. Ticket-wide transitions
    // (issue closed, a person's hold) would make this vacuous, so they are excluded: the question
    // is whether the machine itself can finish a card.
    const edges = new Map<string, Set<string>>();
    for (const { from, transition } of transitions()) {
      if (from === 'ticket') continue;
      edges.set(from, (edges.get(from) ?? new Set()).add(transition.target));
    }
    const isEnd = (path: string) => path.startsWith('ticket.terminal.') || path.startsWith('ticket.human.');
    const onlyHuman: string[] = [];
    for (const [path, node] of states) {
      if (!node.lane || isEnd(path)) continue;
      const seen = new Set<string>();
      const queue = [path];
      let terminal = false;
      let human = false;
      while (queue.length) {
        const here = queue.shift() as string;
        if (seen.has(here)) continue;
        seen.add(here);
        if (here.startsWith('ticket.terminal.')) terminal = true;
        if (here.startsWith('ticket.human.')) human = true;
        for (const next of edges.get(here) ?? []) queue.push(next);
      }
      expect(terminal || human, `${path} reaches neither a terminal nor a human lane`).toBe(true);
      if (!terminal) onlyHuman.push(path);
    }
    // Known: the waits and dead letters can only leave through reconcile or a human lane; anything
    // else appearing here is a new dead end.
    expect(onlyHuman.filter((p) => !p.startsWith('ticket.waits.') && !p.startsWith('ticket.deadLetters.'))).toEqual([]);
  });

  it('no two transitions in one list share a guard', () => {
    // crucible's dead transition: the second of two identical guards can never be taken.
    for (const [path, node] of states) {
      const lists = [...Object.entries(node.on ?? {}).map(([e, l]) => [e, Array.isArray(l) ? l : [l]] as const), ['always', node.always ?? []] as const];
      for (const [event, list] of lists) {
        const guards = list.map((t) => t.guard ?? '(none)');
        expect(new Set(guards).size, `${path} on ${event} repeats a guard`).toBe(guards.length);
      }
    }
  });

  it('every counter guard has an unguarded sibling into a dead-letter or human lane', () => {
    // Step Functions MaxAttempts and SQS maxReceiveCount: a retry counter without a finite exit is
    // an unbounded retry, and Temporal's default of unlimited attempts is the defect to forbid.
    for (const [path, node] of states) {
      for (const [event, raw] of Object.entries(node.on ?? {})) {
        const list = Array.isArray(raw) ? raw : [raw];
        for (const t of list) {
          if (!t.guard?.includes('UnderCap')) continue;
          // A list that falls through to its phase's has one more way to be bounded: the same guard
          // without the cap, which is where the card goes once the cap is spent (the panel's is H1).
          const uncapped = t.guard.split(' and ').filter((atom) => !atom.endsWith('UnderCap') && atom !== 'panelAvailable').join(' and ');
          const fallback = list.find((o) => o.guard === undefined) ?? (uncapped ? list.find((o) => o.guard === uncapped) : undefined);
          expect(fallback, `${path} on ${event}: ${t.guard} has no unguarded sibling`).toBeDefined();
          const target = fallback?.target ?? '';
          expect(
            target.startsWith('ticket.deadLetters.') || target.startsWith('ticket.human.'),
            `${path} on ${event}: the cap fallback goes to ${target}, not a dead-letter or human lane`,
          ).toBe(true);
        }
      }
    }
  });

  it('every lane of every phase that runs a machine answers a machine failing, itself or through its phase', () => {
    // Step Functions: every Task can fail. A throw between two turns is a failure too, so this
    // asks it of every lane in the phase and not only of the states whose entry starts an agent.
    const answers = (path: string): boolean => {
      const parts = path.split('.');
      return parts.some((_, depth) => depth >= 1 && Object.keys(states.get(parts.slice(0, depth + 1).join('.'))?.on ?? {}).includes('AGENT_FAILED'));
    };
    const machinePhases = ['ticket.appraisal.', 'ticket.carving.', 'ticket.work.', 'ticket.review.', 'ticket.landing.', 'ticket.deadLetters.'];
    const silent = LANES.map((l) => l.state).filter((path) => machinePhases.some((phase) => path.startsWith(phase)) && !answers(path));
    expect(silent).toEqual([]);
  });

  it('no agent failure anywhere sends a card to a human lane', () => {
    const parked = transitions().filter(({ event, transition }) => event === 'AGENT_FAILED' && transition.target.startsWith('ticket.human.'));
    expect(parked.map(({ from }) => from)).toEqual([]);
  });

  it('dead-letter lanes exit only to their own phase, a human lane, or carving on re-classification', () => {
    // SQS redrive allow policy by queue: a dead letter goes back to its source or to a person.
    const own: Record<string, string> = { appraisal: 'ticket.appraisal.', carve: 'ticket.carving.', work: 'ticket.work.', review: 'ticket.review.', landing: 'ticket.landing.' };
    for (const { from, event, transition } of transitions()) {
      if (!from.startsWith('ticket.deadLetters.')) continue;
      const phase = from.split('.')[2];
      const ok =
        // A failed triage agent leaves the card where it rests: a machine failure is never a hold.
        (event === 'AGENT_FAILED' && transition.target === from) ||
        transition.target.startsWith(own[phase]) ||
        transition.target.startsWith('ticket.human.') ||
        // The panel is the step before a person: a question triage extracts is weighed there first.
        transition.target === 'ticket.panel.reviewing' ||
        // A person's redrive continues the pull request: catch up first, then the revision, or
        // re-derive from facts when there is no pull request to continue.
        (event === 'REDRIVEN' && ['ticket.landing.catchingUp', 'ticket.work.sentBack', 'ticket.reconcile'].includes(transition.target)) ||
        // Work with a pull request is carried on from the catch-up, never started over.
        (from === 'ticket.deadLetters.work' && ['ticket.carving.toCarve', 'ticket.landing.catchingUp'].includes(transition.target)) ||
        // A retried rejection is a revision, reached through the catch-up when the lane is behind.
        (from === 'ticket.deadLetters.review' && ['ticket.work.sentBack', 'ticket.landing.catchingUp'].includes(transition.target));
      expect(ok, `${from} on ${event} exits to ${transition.target}`).toBe(true);
    }
  });

  it('has no history states', () => {
    // Re-entering a state runs its entry actions, and most entry actions here start an agent.
    for (const [path, node] of states) expect(node.type, `${path} is a history state`).not.toBe('history');
  });

  it('only the three seams are guarded on the line', () => {
    const seams = transitions().filter((t) => t.transition.guard?.includes('lineActive'));
    const events = new Set(seams.map((t) => t.event));
    expect([...events].sort()).toEqual(['APPRAISER_DISPATCHED', 'DISPATCHED', 'FINGERPRINT_CHANGED', 'ALL_CHILDREN_CLOSED', 'KNIFE_DISPATCHED'].sort());
    expect(MACHINE.states?.line?.states?.paused).toBeDefined();
  });
});

describe('a blocker that closes', () => {
  it('sends a completed close through reconcile, never straight to Ready, since the freed card may be unsized, oversized, or still blocked', () => {
    const closed = transitions().filter(({ from, event }) => from.endsWith('blockedBySibling') && event === 'BLOCKER_CLOSED');
    const completed = closed.find(({ transition }) => transition.guard === 'blockerCompleted');
    expect(completed?.transition.target).toBe('ticket.reconcile');
    expect(closed.some(({ transition }) => transition.target === 'ticket.ready.ready')).toBe(false);
  });
});
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