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

View on GitHub
/**
 * Mid-run admission: the work phase's refill. A run's work list used to be fixed when the run
 * started, so anything the run itself made eligible (a dependent whose blocker it merged, a child
 * the knife carved, a trunk's released remainder) waited for the next run. After a lane settles,
 * and once more before the run calls itself idle, the backlog is placed again from the tracker and
 * what is newly Ready joins the run. Placement, holds, claims, blockers, and the size ceiling decide
 * exactly as they do at the start; this module only decides what is new and what the budgets allow.
 */

/** The slice of a placement this module reads: the lane each issue is in, and why. */
export type PlacedIssue = {
  number: number;
  blockedBy?: { nodes: Array<{ number: number; state: string; stateReason?: string | null }> } | null;
};
export type AdmissionPlacement<I extends PlacedIssue> = Map<number, { lane: string; why: string; issue: I }>;

export type AdmissionDeps<I extends PlacedIssue> = {
  /** `--limit`: every issue handed to a worker this run counts, the first batch included. */
  limit: number;
  /** `--appraise-limit`: every issue appraised this run counts. */
  appraiseLimit: number;
  /** False under `--no-appraise`, a dry run, or when the start of the run could not size. */
  canAppraise: () => boolean;
  stopping: () => boolean;
  /** Fetch the base, so appraisers judge, and lanes branch from, what the last merge left. */
  fetchBase: () => void;
  /** Place the backlog from the tracker (the run's `placeBacklog(allIssues())`). */
  place: () => Promise<AdmissionPlacement<I>>;
  /**
   * Appraise the inbox lane, leaving out `skip`, at most `limit` issues; the numbers it appraised,
   * or null when the appraisal lock is held elsewhere and this pass must not size anything.
   */
  appraise: (placement: AdmissionPlacement<I>, skip: (issue: I) => boolean, limit: number) => Promise<number[] | null>;
  /** The run's selection over Ready, in its order, without logging every exclusion again. */
  select: (placement: AdmissionPlacement<I>) => I[];
  log: (line: string) => void;
};

export type Admission<I extends PlacedIssue> = {
  /** Issues handed to a worker this run. */
  readonly dispatched: Set<number>;
  /** Issues appraised this run. */
  readonly appraised: Set<number>;
  /** Records the start-of-run batch, so the refill neither repeats it nor forgets it in the budget. */
  start: (issues: Iterable<number>) => void;
  /** The refill: newly eligible issues, within the budgets, each admitted at most once per run. */
  admit: () => Promise<I[]>;
};

/** Rounds of sizing one refill makes: freed cards, then children their carving created, and so on. */
export const MAX_APPRAISAL_PASSES = 4;

export function createAdmission<I extends PlacedIssue>(deps: AdmissionDeps<I>): Admission<I> {
  const dispatched = new Set<number>();
  const appraised = new Set<number>();
  const reportedStuck = new Set<number>();

  /**
   * A card waiting on a blocker closed without completing never leaves W1 by itself (that branch of
   * `BLOCKER_CLOSED` is not built), so the run says so once instead of leaving it silent.
   */
  const reportStuck = (placement: AdmissionPlacement<I>) => {
    for (const { lane, issue } of placement.values()) {
      if (lane !== 'W1' || reportedStuck.has(issue.number)) continue;
      const blockers = issue.blockedBy?.nodes ?? [];
      if (blockers.length === 0 || blockers.some((b) => b.state !== 'CLOSED')) continue;
      const dead = blockers.filter((b) => b.stateReason !== 'COMPLETED').map((b) => `#${b.number}`);
      if (dead.length === 0) continue;
      reportedStuck.add(issue.number);
      deps.log(`#${issue.number}  waits on ${dead.join(', ')}, closed without completing; a person decides whether it still applies`);
    }
  };

  return {
    dispatched,
    appraised,
    start: (issues) => {
      for (const n of issues) dispatched.add(n);
    },
    admit: async () => {
      if (deps.stopping()) return [];
      const room = deps.limit - dispatched.size;
      if (room <= 0) return [];
      deps.fetchBase();
      let placement = await deps.place();
      reportStuck(placement);
      // Sizing can create work: an oversized card goes to the knife, whose children arrive unsized.
      // Size again until nothing new is unsized, so a refill asked at idle does not end the run with
      // freshly carved children nobody will appraise.
      for (let pass = 0; pass < MAX_APPRAISAL_PASSES; pass++) {
        const budget = deps.appraiseLimit - appraised.size;
        const unsized = [...placement.values()].some(({ lane, issue }) => lane === 'A1' && !appraised.has(issue.number));
        if (!unsized || budget <= 0 || !deps.canAppraise() || deps.stopping()) break;
        const sized = await deps.appraise(placement, (issue) => appraised.has(issue.number), budget);
        if (sized === null) {
          deps.log('the appraisal lock is held elsewhere; cards freed mid-run are sized by the next run');
          break;
        }
        for (const n of sized) appraised.add(n);
        placement = await deps.place();
        if (sized.length === 0) break;
      }
      if (deps.stopping()) return [];
      const admitted = deps
        .select(placement)
        .filter((issue) => !dispatched.has(issue.number))
        .slice(0, room);
      for (const issue of admitted) {
        dispatched.add(issue.number);
        deps.log(`#${issue.number}  admitted mid-run: ${placement.get(issue.number)?.why ?? 'Ready'}`);
      }
      return admitted;
    },
  };
}
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