issue-fix-flow

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

Checklist

• Issue context captured (repro steps, expected behavior)
• Code path located and understood
• Fix implemented with minimal changes
• Tests added/updated if applicable
• Build passes
• Tests pass
• Only relevant files staged
• Commit message includes Closes #<id>
• Changes pushed
• Summary provided