Fix Issue

fix-issue

Fixes one GitHub issue end-to-end inside a single interactive session, with exactly one human approval gate — before any code is written. A second gate, PR review, happens on GitHub afterward and is outside this skill's control.

Do not run this unattended. If the person who invoked /fix-issue is not present to approve the spec at Step 6, stop and wait there. Never skip Step 6 and go straight to implementation, no matter how small the fix looks.

Announce at start: "Using fix-issue to work ``."

Step 1: Resolve the target repo

Parse / and the issue number out of the issue URL, e.g. https://github.com//-app/issues/565 → owner=, repo=-app, issue_number=565. If the URL doesn't match this pattern, stop and tell the user the URL couldn't be parsed — do not guess at owner/repo/issue values.

Find the local checkout by matching git remotes — never hardcode a repo-name → path table, since this workspace's repo layout has drifted before. Substitute the owner/repo values parsed above before running this — the variables are shown unquoted here for clarity, but must be bound to real values first.

for d in */; do
  if [ -d "$d/.git" ]; then
    remote=$(git -C "$d" remote get-url origin 2>/dev/null)
    case "$remote" in
      *"$owner/$repo".git|*"$owner/$repo") echo "$d" ;;
    esac
  fi
done

• Exactly one match → that directory is $repo_dir. Use it as the working directory

for every remaining step.

• No match → ask: "No local checkout of $owner/$repo found here. Clone it into this

workspace?" On yes, run gh repo clone $owner/$repo from the workspace root, then use the newly created directory as $repo_dir. On no, stop the pipeline here — do not guess at a repo location.

• More than one match → stop and ask the user which directory to use. Never guess.

Step 2: Sync

In $repo_dir:

git status --short

If this prints anything at all (modified, staged, or untracked files), stop and ask the user how to proceed — do not stash or discard anything automatically. Only continue once the tree is confirmed clean (empty output).

Find the default branch and sync it:

default_branch=$(git remote show origin | grep "HEAD branch" | awk '{print $NF}')
git checkout "$default_branch"
git pull

Step 3: Fetch the issue

gh issue view  --json title,body,comments,labels,url

If this errors (bad URL, no access, issue deleted), stop and report the error to the user — do not guess at issue content.

Step 4: Verify the issue still reproduces

Using the issue's title/body/comments, identify the code paths it implicates and read them on the current default branch (the one just synced in Step 2). This is code-read only — never start services, run the app, or execute a repro script to check this.

Reason explicitly about whether the described behavior is still present given what the code does today. Two outcomes:

• Already fixed: state clearly what changed (or why the described behavior can no longer

occur) and stop the pipeline entirely — do not write a spec, do not touch code, do not open a PR. Report this to the user as the final output of this run.

• Still reproduces: continue to Step 5 with a concrete understanding of the root cause —

Step 5's spec depends on being able to cite exact files/lines, not just repeat the issue text.

Step 5: Write the fix spec

Write a markdown spec to $repo_dir/docs/issue-fixes/--spec.md (create the docs/issue-fixes/ directory if it doesn't exist yet — this is a new, per-repo convention, not tied to any existing spec location in that repo). Use exactly these sections:

# Issue #: 

## Problem

## Root cause

## Proposed fix

## Affected files
- `path/to/file.ext` — 

## Risks / edge cases

## Test plan

Do not leave any section empty — if a section genuinely doesn't apply, say why in one sentence rather than omitting it.

Step 6: Gate 1 — get spec approval (STOP AND WAIT)

This is the pipeline's one required human approval gate. Call EnterPlanMode. Once inside plan mode, write the full content of the Step 5 spec file into the plan file specified in the plan-mode system message (copy it in — don't just reference its path). Then call ExitPlanMode, which reads that file and surfaces it to the user for approval.

• Approved → before continuing to Step 7, make sure the repo spec file at

$repo_dir/docs/issue-fixes/--spec.md matches exactly what was approved — if the spec was revised during this gate (edited in the plan file rather than the repo file, since only the plan file is writable inside plan mode), overwrite the repo spec file with the approved content now, before moving on. Do not re-summarize or re-confirm the approval itself — the approval is the gate.

• Changes requested → go back to Step 5, revise the spec file with the requested

changes, and re-present it through this same gate. Repeat until approved or the user says to stop.

• User aborts → end the pipeline here. Do not implement anything, do not open a PR.

Never proceed past this step without an explicit approval from ExitPlanMode. If the person who ran /fix-issue is not available to respond, wait — do not time out into "assume approved."

Step 7: Implement with TDD

Only reachable after Step 6's approval.

1. Write a failing test that reproduces the issue, following the spec's "Test plan"

section. Run it and confirm it fails for the expected reason (not a setup error).

1. Implement the fix described in the spec's "Proposed fix" section.
2. Run the full test suite for the affected package/module (not just the new test).

If the suite isn't green: stop here, do not proceed to Step 8. Report exactly what's failing and ask the user how to proceed — do not open a PR against a red suite, and do not loosen the new test to force it to pass.

For unfamiliar failures, use the superpowers:systematic-debugging skill rather than guessing at fixes.

Step 8: Branch, commit, push, open PR, request reviewers

branch="fix/issue--"
git checkout -b "$branch"
git add  docs/issue-fixes/--spec.md
git commit -m "fix: 

Fixes #"
git push -u origin "$branch"

Open the PR and request review from every collaborator except the PR author in one call:

pr_author=$(gh api user --jq .login)
reviewers=$(gh api repos///collaborators --jq '.[].login' | grep -v "^${pr_author}$" | paste -sd, -)
default_branch=$(git remote show origin | grep "HEAD branch" | awk '{print $NF}')
gh pr create --title "" --body "Fixes #. See docs/issue-fixes/--spec.md for the fix spec." --base "$default_branch" --reviewer "$reviewers"

If the collaborators call fails or returns nothing (permissions, rate limit): still run gh pr create without --reviewer, and tell the user reviewers weren't auto-assigned — do not block PR creation on this. The same fallback applies if gh pr create itself fails because of a bad/rejected reviewer list (GitHub rejects requesting review from the PR's own author with a 422) — still create the PR, note reviewers weren't auto-assigned, don't block.

Report the PR URL (printed by gh pr create) as the final output of this skill. Gate 2 — human review — now happens on GitHub; this skill's job is done.

Error handling

| Situation | Behavior | |---|---| | Uncommitted changes in $repo_dir before sync | Stop, ask — never auto-stash or discard | | Issue URL doesn't parse, or repo not found and user declines the clone | Stop, ask | | Multiple local repos match the same remote | Stop, ask the user to disambiguate | | Issue no longer reproduces (Step 4) | Stop after Step 4, report, no spec/code/PR | | User requests spec changes at Gate 1 (Step 6) | Revise spec, re-present; loop until approved or aborted | | Test suite fails after implementation (Step 7) | Stop before Step 8, report failure, ask how to proceed | | Collaborator lookup fails or is empty (Step 8) | Open the PR anyway; note reviewers weren't auto-assigned |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gssajith
• Source: gssajith/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.