home / skills / freekmurze / dotfiles / fix-github-issue

fix-github-issue skill

safe

This skill helps you fix GitHub issues by creating feature branches, running local tests, and generating PRs when tests pass.

npx playbooks add skill freekmurze/dotfiles --skill fix-github-issue

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.3 KB

---
name: fix-github-issue
description: Fix GitHub issues using gh CLI. Use when asked to fix, resolve, or address a GitHub issue. Creates fixes on separate branches, runs tests locally, and creates PRs when tests pass. Requires gh CLI authenticated and repo cloned locally.
---

# GitHub Issue Fixer

Fix GitHub issues by implementing solutions on feature branches with proper testing.

## Prerequisites

- `gh` CLI installed and authenticated
- Repository cloned locally
- Test command available (auto-detected or specified)

## Workflow

### 1. Understand the Issue

```bash
gh issue view <issue-number>
```

Read the issue thoroughly.

### 2. Create Feature Branch

```bash
git checkout main && git pull origin main
git checkout -b fix-<short-description>
```

Branch naming: `fix-description` (lowercase, hyphens).

### 3. Analyze the Codebase

Before coding, understand the relevant parts:
- Locate files related to the issue
- Check existing tests for patterns
- Review any referenced code in the issue

### 4. Implement the Fix

Make minimal, focused changes that address the issue. Follow existing code style and patterns.

### 5. Run Tests Locally

Detect and run the test suite. Most likely it will be pest or phpunit. Take a look what is defined in composer.json or the testing github file.

**Tests must pass locally before proceeding.** If tests fail:
1. Analyze failures
2. Fix the implementation
3. Re-run until all pass

### 6. Commit Changes

```bash
git add -A
git commit -m "Fix #<issue-number>: <concise description>"
```

Use conventional commit message referencing the issue number.

### 7. Push and Create PR

```bash
git push -u origin fix/issue-<issue-number>-<short-description>
gh pr create --title "Fix #<issue-number>: <title>" --body "Fixes #<issue-number>

## Changes
- <bullet points of changes>

## Testing
- All local tests pass
- <any additional testing done>"
```

### 8. Monitor CI

```bash
gh pr checks --watch
```

If CI fails:
1. Review the failure: `gh run view <run-id> --log-failed`
2. Fix locally
3. Push additional commits
4. Repeat until CI passes

## Quick Reference

```bash
# View issue
gh issue view 123

# Create branch
git checkout -b fix/issue-123-description

# After fixing and tests pass
git add -A && git commit -m "Fix #123: description"
git push -u origin fix/issue-123-description
gh pr create --fill

# Watch CI
gh pr checks --watch
```

Overview

This skill fixes GitHub issues using the gh CLI by creating focused feature branches, running tests locally, and opening pull requests when tests pass. It is designed for repositories cloned locally with gh authenticated and a working test command. The workflow enforces small, test-backed changes and CI monitoring to ensure reliable fixes.

How this skill works

I inspect the issue via gh issue view, create a dedicated fix branch from main, implement a minimal change that follows project style, and run the local test suite until all tests pass. I commit with a conventional message referencing the issue, push the branch, create a PR with a descriptive body, and watch CI checks until they succeed. If tests or CI fail, I iterate locally until green.

When to use it

When asked to fix, resolve, or address a specific GitHub issue in a repo cloned locally.
When you have gh CLI installed and authenticated for the target GitHub account.
When the repository includes a test command that can be run locally.
When you want changes isolated on a dedicated branch and tracked by a PR.
When you need to ensure CI passes before merging a fix.

Best practices

Pull latest main before creating the fix branch and use clear hyphenated branch names like fix/issue-123-short-desc.
Make minimal, focused changes that directly address the issue and follow existing style and patterns.
Run the full test suite locally and fix all failures before pushing changes.
Reference the issue number in commit messages and PR titles (e.g., Fix #123: concise description).
Use gh pr create --fill or a detailed body listing changes and testing performed.
Monitor CI with gh pr checks --watch and iterate until CI is green.

Example use cases

Fix a shell prompt bug in my dotfiles where zsh option causes incorrect behavior; run local zsh checks and open a PR.
Resolve a Vimscript mapping conflict reported in an issue by editing the relevant vimrc file, running any available lint/tests, and creating a PR.
Address a broken install script by adding a guard and unit test, then push a fix branch and create a PR.
Update documentation referenced by an issue, ensure any docs-build tests pass, and submit the PR for review.
Refactor a small function to fix a regression, run tests locally, and open a PR that references the issue.

FAQ

What do I need before using this skill?

You need gh CLI installed and authenticated, the repository cloned locally, and a working test command for the project.

What if tests or CI fail after my change?

Investigate failures locally with test logs, fix the implementation, re-run tests, commit fixes, push, and let CI re-run until it passes.