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/board-writer.ts

View on GitHub
/**
 * Writes cards onto the operator's board: the `onLane` hook a driver hands the fix pipeline, and
 * the placement-by-facts a driver runs before it starts on an issue.
 *
 * The board is a projection of the tracker, so a write here must never fail a lane: every error
 * is logged and swallowed. Field and option ids are read once per process from the board the
 * pointer names and matched by name, never stored, because rewriting the lane set reassigns
 * every option id (see references/adopting.md, "The board").
 */

import { existsSync, readFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import type { LaneEvent } from '../../fix-github-issue/lib/context.ts';
import { dlqPhase } from '../../fix-github-issue/lib/labels.ts';
import { isFinishing, isStopping } from '../../fix-github-issue/lib/shell.ts';
import type { Board } from '../board.ts';
import { type Lane, laneByKey, laneByLabel, laneLabel, phaseLabel } from './lanes.ts';

type Field = { id: string; name: string; options: Array<{ id: string; name: string }> };

export type BoardWriter = {
  board: Board;
  /** Resolve when no card write is outstanding; never rejects. */
  settled: () => Promise<void>;
  /** The `onLane` hook: ensure the issue is on the board and set its Status and Phase. True when both writes landed. */
  onLane: (event: LaneEvent) => boolean;
  /** Read the lane the card is in now, or undefined when the issue is not on the board. */
  laneOf: (issue: number) => Lane | undefined;
  /** Every card on the board with its lane and its issue's state and labels, in one read. Throws on a failed read. */
  snapshot: () => Map<number, Card>;
};

/** Give a stopping driver's card writes a bounded wait before it exits. */
export async function waitForBoard(writer: Pick<BoardWriter, 'settled'> | undefined, timeoutMs = 10_000): Promise<void> {
  if (!writer) return;
  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    await Promise.race([
      writer.settled(),
      new Promise<void>((resolve) => { timer = setTimeout(resolve, timeoutMs); }),
    ]);
  } finally {
    clearTimeout(timer);
  }
}

export type Card = {
  item: string;
  /** Undefined when the Status option is empty or not one the lane table knows. */
  lane: Lane | undefined;
  state: 'OPEN' | 'CLOSED';
  labels: string[];
};

function gh(args: string[]): string {
  const proc = Bun.spawnSync(['gh', ...args], { stderr: 'pipe', stdout: 'pipe' });
  if (proc.exitCode !== 0) throw new Error(`gh ${args.slice(0, 3).join(' ')}: ${proc.stderr.toString().trim()}`);
  return proc.stdout.toString().trim();
}

function graphql(query: string): unknown {
  const out = gh(['api', 'graphql', '-f', `query=${query}`]);
  const parsed = JSON.parse(out) as { data: unknown; errors?: Array<{ message: string }> };
  if (parsed.errors?.length) throw new Error(parsed.errors.map((e) => e.message).join('; '));
  return parsed.data;
}

/** The board pointer `board.ts` wrote, or undefined when this repository has no board yet. */
export function readBoardPointer(repoRoot: string, worktreeRoot: string): Board | undefined {
  const pointer = join(resolve(repoRoot, worktreeRoot, 'runs'), 'board.json');
  if (!existsSync(pointer)) return undefined;
  return JSON.parse(readFileSync(pointer, 'utf8')) as Board;
}

/**
 * A writer bound to one board. Reads the Status and Phase fields once; a lane whose option is
 * missing from the board (the lane set changed and lanes.ts has not been rerun) is reported and
 * skipped rather than guessed.
 */
export function createBoardWriter(board: Board, repo: string, log: (message: string) => void): BoardWriter {
  let fields: { status: Field; phase: Field } | null = null;
  const items = new Map<number, string>();

  const readFields = () => {
    if (fields) return fields;
    const data = graphql(
      `{ node(id:"${board.id}") { ... on ProjectV2 { fields(first:50) { nodes { ... on ProjectV2SingleSelectField { id name options { id name } } } } } } }`,
    ) as { node: { fields: { nodes: Array<Partial<Field>> } } };
    const all = data.node.fields.nodes.filter((f): f is Field => typeof f.id === 'string' && Array.isArray(f.options));
    const status = all.find((f) => f.name === 'Status');
    const phase = all.find((f) => f.name === 'Phase');
    if (!status || !phase) throw new Error(`board #${board.number} lacks a Status or Phase field; run lanes.ts`);
    fields = { status, phase };
    return fields;
  };

  const itemFor = (issue: number): string => {
    const known = items.get(issue);
    if (known) return known;
    const url = `https://github.com/${repo}/issues/${issue}`;
    // item-add is idempotent on GitHub's side: an issue already on the board returns its item.
    const id = gh(['project', 'item-add', String(board.number), '--owner', board.owner, '--url', url, '--format', 'json', '--jq', '.id']);
    items.set(issue, id);
    return id;
  };

  const setOption = (item: string, field: Field, optionName: string) => {
    const option = field.options.find((o) => o.name === optionName);
    if (!option) throw new Error(`board #${board.number} has no ${field.name} option '${optionName}'; run lanes.ts`);
    gh(['project', 'item-edit', '--id', item, '--project-id', board.id, '--field-id', field.id, '--single-select-option-id', option.id]);
  };

  const onLane = (event: LaneEvent): boolean => {
    // A stopping run settles nothing, its cards included; the next run start places them by facts.
    if (isStopping() && !isFinishing()) return false;
    try {
      const lane = laneByKey(event.lane);
      const { status, phase } = readFields();
      const item = itemFor(event.issue);
      setOption(item, status, laneLabel(lane));
      setOption(item, phase, phaseLabel(lane.phase));
      log(`#${event.issue}  board: ${lane.key} ${lane.name}${event.note ? ` (${event.note})` : ''}`);
      return true;
    } catch (error) {
      log(`#${event.issue}  board write failed: ${(error as Error).message}`);
      return false;
    }
  };

  const laneOf = (issue: number): Lane | undefined => {
    try {
      const raw = gh(['project', 'item-list', String(board.number), '--owner', board.owner, '--format', 'json', '--limit', '500']);
      const parsed = JSON.parse(raw) as { items: Array<{ content?: { number?: number }; status?: string; id: string }> };
      const item = parsed.items.find((i) => i.content?.number === issue);
      if (!item) return undefined;
      items.set(issue, item.id);
      const { status } = readFields();
      const option = status.options.find((o) => o.name === item.status);
      return option ? laneByLabel(option.name) : undefined;
    } catch (error) {
      log(`#${issue}  board read failed: ${(error as Error).message}`);
      return undefined;
    }
  };

  /**
   * One GraphQL read per hundred cards, paginated: the item id, the Status option name, and the
   * issue's number, state, and labels. Item ids are remembered so a later move needs no item-add.
   */
  const snapshot = (): Map<number, Card> => {
    const cards = new Map<number, Card>();
    let cursor: string | null = null;
    for (;;) {
      const after = cursor ? `, after:"${cursor}"` : '';
      const data = graphql(
        `{ node(id:"${board.id}") { ... on ProjectV2 { items(first:100${after}) { pageInfo { hasNextPage endCursor } nodes { id status: fieldValueByName(name:"Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } content { ... on Issue { number state labels(first:50) { nodes { name } } } } } } } } }`,
      ) as {
        node: {
          items: {
            pageInfo: { hasNextPage: boolean; endCursor: string | null };
            nodes: Array<{ id: string; status: { name?: string } | null; content: { number?: number; state?: 'OPEN' | 'CLOSED'; labels?: { nodes: Array<{ name: string }> } } | null }>;
          };
        };
      };
      for (const node of data.node.items.nodes) {
        const number = node.content?.number;
        if (number === undefined || !node.content?.state) continue; // a draft item or a pull request card
        items.set(number, node.id);
        cards.set(number, {
          item: node.id,
          lane: node.status?.name ? laneByLabel(node.status.name) : undefined,
          state: node.content.state,
          labels: (node.content.labels?.nodes ?? []).map((l) => l.name),
        });
      }
      if (!data.node.items.pageInfo.hasNextPage) break;
      cursor = data.node.items.pageInfo.endCursor;
    }
    return cards;
  };

  return { board, onLane, laneOf, snapshot, settled: async () => {} };
}

/**
 * Where an issue's facts put it before a driver touches it: the reconcile precedence of
 * references/state-machine.md, reduced to what a single-issue driver can read cheaply. Returns the
 * lane key and the fact that decided it.
 */
export function placeByFacts(facts: {
  state: 'OPEN' | 'CLOSED';
  labels: string[];
  /** The pull requests that own the issue, newest first: open ones, and merged ones for a closed issue. */
  pulls: Array<{ number: number; isDraft: boolean; merged: boolean }>;
  points?: number;
  ceiling: number;
  /** True when a blocked-by edge points at an issue not closed as completed. */
  blocked?: boolean;
  /** True when the issue has an open sub-issue: a trunk whose children must move first. */
  openChildren?: boolean;
  /** The run whose live claim stands on the issue, when it is not this run's. */
  claimedBy?: string;
  /** True when an ancestor is paused, which pauses everything beneath it. */
  pausedAbove?: boolean;
}): { lane: string; why: string } {
  const has = (label: string) => facts.labels.includes(label);
  const merged = facts.pulls.find((p) => p.merged);
  if (facts.state === 'CLOSED') return merged ? { lane: 'T1', why: `closed; PR #${merged.number} merged` } : { lane: 'T2', why: 'closed' };
  if (merged) return { lane: 'T1', why: `PR #${merged.number} merged, issue still open` };
  // The machine sends a skipped issue off the board; a card that already exists for one sits in
  // the human lane, since a person's never is the one hold no seat may lift.
  if (has('loop/skip')) return { lane: 'H2', why: 'loop/skip' };
  if (has('needs-decision')) return { lane: 'H1', why: 'needs-decision' };
  if (has('needs-human')) return { lane: 'H2', why: 'needs-human' };
  if (has('loop/parked')) return { lane: 'H3', why: 'loop/parked' };
  // A decision panel runs inside the process that raised its question: one standing at placement
  // is another run's, and the burndown holds one whose run died before placing anything.
  if (has('loop/deliberating')) return { lane: 'W3', why: 'a decision review is weighing it in another run' };
  const dead = dlqPhase(facts.labels.map((name) => ({ name })));
  if (dead) return { lane: { appraisal: 'Q1', carve: 'Q2', work: 'Q3', review: 'Q4', landing: 'Q5' }[dead], why: `loop/dlq: ${dead}` };
  if (has('loop/paused') || facts.pausedAbove) return { lane: 'W2', why: has('loop/paused') ? 'loop/paused' : 'an ancestor is paused' };
  // Another run's live claim: the card waits for it, whatever else is true of the issue.
  if (facts.claimedBy) return { lane: 'W3', why: `claimed by ${facts.claimedBy}` };
  if (has('loop/released')) return { lane: 'C7', why: 'loop/released' };
  if (has('loop/carved') || facts.labels.some((l) => l.startsWith('loop/carve-gen:'))) return { lane: 'C5', why: 'a carved trunk' };
  if (facts.openChildren) return { lane: 'C5', why: 'it has an open child' };
  const open = facts.pulls.find((p) => !p.merged);
  if (open) return open.isDraft ? { lane: 'D3', why: `draft PR #${open.number}` } : { lane: 'E1', why: `ready PR #${open.number}` };
  if (facts.blocked) return { lane: 'W1', why: 'a blocker is not closed as completed' };
  if (facts.points !== undefined && facts.points > facts.ceiling) return { lane: 'C1', why: `size ${facts.points} over the ceiling of ${facts.ceiling}` };
  if (facts.points !== undefined) return { lane: 'B1', why: `size ${facts.points}` };
  return { lane: 'A1', why: 'unsized' };
}
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