fix-gh-issue

name	fix-gh-issue
description	Fix a single GitHub issue end-to-end using wt. Creates a worktree, implements the fix, waits for CI, squash-merges, and removes the worktree. Trigger phrases: 'fix issue', 'fix gh issue', 'work on issue', 'start issue', 'launch issue'. Use when this capability is needed.

fix-gh-issue Skill

Orchestrate a single GitHub issue through the full lifecycle: worktree → implement → PR → CI → squash-merge → cleanup.

Works in any git repository with a GitHub remote.

Inputs

Extract from the user message:

• ISSUE — GitHub issue number (required, e.g. 42)
• BRANCH — branch name (optional — auto-derived if omitted)
• PROMPT — custom prompt describing the fix (optional — default below)

If ISSUE is missing, ask before proceeding.

Derived values

Resolve at runtime — do not hardcode paths or repo names:

REPO_PATH=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_PATH")

If BRANCH was not provided, derive it from the issue title:

BRANCH=$(gh issue view "$ISSUE" --json number,title \
  --jq '"fix/\(.number)-\(.title | gsub("^[a-z]+: "; "") | ascii_downcase | gsub("[^a-z0-9]+"; "-") | gsub("(^-|-$)"; "") | split("-")[0:6] | join("-"))"')

Then:

BRANCH_SAFE="${BRANCH//\//-}"
WORKTREE_PATH="${REPO_PATH}/../${REPO_NAME}.${BRANCH_SAFE}"

Default prompt (if none supplied):

Fix GitHub issue #<ISSUE> on branch <BRANCH>.
Run all tests before pushing.
Create a PR that closes #<ISSUE>.

Phase 1 — Create worktree

wt -C "$REPO_PATH" switch --create "$BRANCH" --no-cd

Skip if $WORKTREE_PATH already exists.

Phase 2 — Implement the fix

Work directly in $WORKTREE_PATH. Follow the prompt to implement, test, commit, and push. Create the PR:

gh pr create --title "..." --body "Closes #<ISSUE>" --head "$BRANCH"

Phase 3 — Wait for PR

If the PR was created by a separate agent or process, poll every 60 seconds (up to 2 hours):

gh pr list --head "$BRANCH" --json number --jq '.[0].number'

gh auto-detects the repo from the git remote. Log progress every 10 minutes. If no PR after 2 hours, stop and report.

Phase 4 — Wait for CI

gh pr checks "$PR_NUMBER" --watch --fail-fast

If CI fails: fix the issue in $WORKTREE_PATH, push, then re-run this phase.

Phase 5 — Squash-merge

gh pr merge "$PR_NUMBER" --squash --delete-branch

Phase 6 — Remove worktree

wt -C "$REPO_PATH" remove -D "$BRANCH"

Parallel execution

Each issue runs in its own isolated worktree — no filesystem conflicts. Run multiple issues in parallel freely. If two branches modify the same file, GitHub will flag the merge conflict on the PR when it's time to merge; deal with it then.

Integration test limitation: Integration tests share a single Consul and Redis instance with hardcoded keys. Running go test -tags=integration from two worktrees simultaneously will cause key collisions and flaky failures. Only one worktree should run integration tests at a time — coordinate manually or stagger the test runs.

---

Source: beatlabs/harvester — distributed by TomeVault.