Fix GitHub Issue

One issue in, one outcome out: merged, parked, handed-off, closed, dlq, or failed when it ran, and left-alone, busy, not-run, stopped, or lease-lost when it did not settle the issue (references/pipeline.md says what each means). Internally it is a coder (code-github-issue), then a prover on a fresh context (prove-github-issue), then a review, then a landing, revising until the issue's review budget is spent. Each seat ends at a fact on the remote, and the driver moves the card between them: the coder at a pushed commit it announces on the issue, the prover at a ready pull request whose head is the proven commit.

Invoked by burn-down-github-issues, once per Ready card and once per floor incident, through fixIssue.

The pipeline is shared; the repository is config. Nothing here is copied into a repository. Everything true of a repository (remotes, branches, commands, path aliases, invalidation paths) lives in a config file at that repository's root, and the pipeline refuses to start without one, naming the missing file and the fields it lacks.

Every stage takes an explicit context rather than reading module state, so one process can run two pipelines against two configurations without either seeing the other's queue, seats (the roles an agent fills: worker, reviewer, confirmer), or run directory. That is what makes fixIssue callable as the fix seat of a larger loop.

When to use it

• One issue you already believe is real and small enough, to be fixed unattended.
• As the fix stage of another driver: import lib/pipeline.ts and call fixIssue(ctx, issue, { maxPoints }), building the context with lib/context.ts.

Skip it for an issue you are working interactively, for anything blocked on a product decision, and for work whose remedy is a judgement call rather than a change.

Run it

From inside the target repository (any directory of it, including a worktree):

bun run <this-skill-dir>/fix.ts --issue <n>
bun run <this-skill-dir>/fix.ts --issue <n> --dry-run
bun run <this-skill-dir>/fix.ts --issue <n> --max-points 8   # raise the size ceiling for this issue only
bun run <this-skill-dir>/fix.ts --issue <n> --worker codex:gpt-5.6-sol --reviewer claude:claude-opus-5
bun run <this-skill-dir>/fix.ts --issue <n> --confirmer claude:claude-opus-5   # the seat that re-checks a close the worker proposes
bun run <this-skill-dir>/fix.ts --issue <n> --redrive        # lift a park or a dead letter and continue the issue's pull request
bun run <this-skill-dir>/fix.ts --issue <n> --land           # a person's go-ahead past the merge boundary for an approved pull request
bun run <this-skill-dir>/fix.ts --issue <n> --resume-pr <pr> # continue that open pull request rather than open another

<this-skill-dir> is the filesystem path of this directory wherever the collection is checked out or installed; it is a path, not a skill name. --worker, --reviewer, and --confirmer take engine[:model] specs resolved against the engine registry in lib/engines.ts, and a flag beats the config for the run it is given on. Without --confirmer the confirmer is the config's, else the config's reviewer (--reviewer does not change it), and it must be a different engine from the worker. --redrive removes loop/parked and every loop/dlq: <phase> label, clears the review and attempt counters, counts the redrive as loop/redrives: N, and continues the newest open pull request that references the issue; --resume-pr names that pull request instead. --land is a person's go-ahead past the merge boundary for a pull request it parked: it lifts only that park, and the pull request is re-proved, re-reviewed, and landed with every other gate in force; it refuses a dead letter or any other park (references/pipeline.md, "The merge boundary"). The command exits non-zero when the fix failed.

The config it reads

fix-github-issue.config.ts at the invoking checkout's root when there is one, and the sibling burndown skill's burn-down-github-issues.config.ts otherwise, reading only the fields it needs. A repository that already adopted the burndown gets this command without writing a second file.

The project block is the repository vocabulary the prompts are rendered with, plus the path aliases and invalidation paths the staleness walk reads. The knobs this pipeline enforces are PipelineKnobs in lib/config.ts, with their defaults in PIPELINE_DEFAULTS beside it; this command adds maxPoints. The template and the fields that actually bite are in the burndown skill's references/adopting.md.

Read next

Hard dependencies

• The prove-work-on-github skill, loaded by name in the worker and reviewer prompts; the pull master's staleness rule implements its references/freshness-and-reproof.md.
• Bun, which runs fix.ts.
• gh authenticated with push and merge rights on the target repository.
• The CLIs the seats name (by default codex and claude), on PATH. Keep worker and reviewer on different engines; a reviewer built from the same model as the author shares its blind spots by construction.

The ceiling, named

The pipeline executes the tracker, not your intent: an internally coherent issue pointing the wrong way is implemented competently in the wrong direction, and the only guard is the convention docs the config names. Issue bodies and comments are an untrusted instruction channel read by agents running with their approval gates bypassed; the worktree confinement is a prompt contract, not a sandbox, so run this only on trackers whose authors you trust as far as the credentials it holds. The merge boundary computes migration and ci from the diff's paths, but data and stored-string are runtime effects a path cannot reveal; for those it holds two independent self-reports and parks rather than trusts. The reviewer runs as the same forge account (the code host's account, GitHub here) as the worker, so its independence is model-level, not identity-level. And of the five dead-letter queues only the review queue has been exercised end to end, by a redrive that continued a parked pull request to a merge; the others are written, not proven.