GitHub Issue Fix Flow

Overview

Resolve a GitHub issue from intake through fix, validation, and push using gh CLI, local edits, and git.

Workflow

1) Intake and Issue Context

Get full issue context:

gh issue view <id> --comments

If repo is unclear:

gh repo view --json nameWithOwner

Capture from the issue:

Reproduction steps
Expected behavior
Maintainer notes or labels
Related issues or PRs

2) Locate the Code Path

Search for relevant code:

# Find files related to the issue
rg -n "keyword from issue"

# Find function definitions
rg -n "func relevantFunction"

# Find type definitions
rg -n "struct|class|enum RelevantType"

Read relevant code paths and understand:

Entry points
Data flow
Existing patterns and conventions

3) Implement the Fix

Guidelines:

Edit the minimal set of files
Keep changes aligned with existing architecture and style
Add tests when behavior changes and coverage is practical
Follow repo-specific conventions (check CONTRIBUTING.md, AGENTS.md, CLAUDE.md)

4) Build and Test

For Swift/Xcode projects:

# Build
swift build
# or
xcodebuild -scheme MyApp -destination 'platform=macOS' build

# Test
swift test
# or
xcodebuild -scheme MyAppTests -destination 'platform=macOS' test

For other projects, use appropriate build/test commands.

Report warnings or failures - do not hide them.

5) Commit and Push

Check for unrelated changes:

git status --short
git diff

Stage only the fix:

git add <specific files>

Commit with closing message:

git commit -m "Fix: <description>

Closes #<issue number>"

Push:

git push

6) Report Back

Provide summary:

What changed and where
Test results (including any failures)
Follow-ups or blocked items

Quick Reference

Task	Command
View issue	`gh issue view <id> --comments`
List issues	`gh issue list`
View repo	`gh repo view --json nameWithOwner`
Create branch	`git checkout -b fix/issue-<id>`
Stage files	`git add <files>`
Commit	`git commit -m "Fix: ... Closes #<id>"`
Push	`git push -u origin HEAD`
Create PR	`gh pr create --fill`

Commit Message Format

Fix: Brief description of the fix

More detailed explanation if needed.
- What was the problem
- How it was fixed
- Any notable changes

Closes #123

Branch Naming

# Feature
git checkout -b feature/issue-123-add-feature

# Bug fix
git checkout -b fix/issue-123-fix-bug

# Refactor
git checkout -b refactor/issue-123-cleanup

PR Workflow (Optional)

If working on a branch for PR:

# Create branch
git checkout -b fix/issue-<id>

# Make changes, commit
git add .
git commit -m "Fix: description (closes #<id>)"

# Push and create PR
git push -u origin HEAD
gh pr create --fill

issue-fix-flow