# Fix Issue

> Fix a GitHub issue end-to-end - sync the repo, verify the issue still reproduces by reading code, write a fix spec, pause for human approval, implement with TDD, open a PR and request review from every collaborator. Trigger: /fix-issue <github-issue-url>

- **Type:** Skill
- **Install:** `agentstack add skill-gssajith-claude-skills-fix-issue`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gssajith](https://agentstack.voostack.com/s/gssajith)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gssajith](https://github.com/gssajith)
- **Source:** https://github.com/gssajith/claude-skills/tree/master/skills/fix-issue

## Install

```sh
agentstack add skill-gssajith-claude-skills-fix-issue
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

```bash
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`:

```bash
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:

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

## Step 3: Fetch the issue

```bash
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:

```markdown
# 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).
2. Implement the fix described in the spec's "Proposed fix" section.
3. 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

```bash
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:

```bash
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](https://github.com/gssajith)
- **Source:** [gssajith/claude-skills](https://github.com/gssajith/claude-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gssajith-claude-skills-fix-issue
- Seller: https://agentstack.voostack.com/s/gssajith
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.