simiancraft/simiancraft-skills / skills/burn-down-github-issues
burn-down-github-issues
UnverifiedRun 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.
lib/machine.test.ts
View on GitHubimport { 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);
});
});
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |