Fix GitHub Issue

Plan, implement, and submit a PR for a GitHub issue using git worktrees for isolation.

Codex note: This skill references Claude Code subagents (

Task(...)

functions.shell_command

multi_tool_use.parallel

../../COMPATIBILITY.md

Phase 1: Plan

1. Set up worktree

Before anything else, create an isolated worktree for this issue:

scripts/setup-worktree.sh $ISSUE_NUMBER

This will:

• Validate prerequisites (gh auth, git repo, origin remote)
• Checkout main and pull latest changes
• Create a new worktree at

  .worktrees/issue-$ISSUE_NUMBER

• Create and checkout a branch

  issue-$ISSUE_NUMBER

• Output the path to cd into

All subsequent work happens in the worktree, keeping your main repo clean.

Options:

• --no-worktree

  : Work directly on a branch without creating a worktree (useful for simple changes)

Note: The script auto-adds

.worktrees/

.gitignore

If setup fails:

• "Not in a git repository": Run from within a git repo
• "gh not authenticated": Run

  gh auth login

• "No origin remote": Add one with

  git remote add origin <url>

• "Uncommitted changes": Commit or stash your changes first
• "Could not fast-forward": Your local main has diverged; resolve manually

2. Load issue context

scripts/load-issue.sh $ISSUE_NUMBER

Fetches issue details, comments, labels, and related PRs.

From the output, identify:

• Main objective from the issue description
• Clarifications, constraints, or scope changes from comments
• Proposed solutions or implementation hints from the author or maintainers
• Any blockers, dependencies, or related issues mentioned

3. Explore the codebase

Locate affected files and review current implementation. Identify integration points, dependencies, and side effects.

4. Create plan

Analyse the issue and produce a plan using templates/plan.md:

• Summary, root cause analysis, implementation steps
• Testing approach, risks, complexity assessment

Example plan output:

# Plan: Fix null pointer in user service

**Issue:** #123 - https://github.com/org/repo/issues/123

## Summary
User service crashes when processing requests with missing optional fields.

## Analysis
The `processUser` function at `src/services/user.ts:45` accesses `user.profile.name`
without checking if `profile` exists. This was introduced in commit abc123.

## Implementation Plan
1. Add null check for `user.profile` in `processUser`
2. Add fallback default values for optional fields
3. Add unit test for the null case

## Testing/Validation
- [ ] Unit test: processUser with null profile
- [ ] Unit test: processUser with partial profile
- [ ] Integration test: API endpoint with minimal payload

## Risks/Edge Cases
- Other callers may rely on the exception being thrown
- Profile field is used in 3 other places (checked: all safe)

## Complexity
**Low** - Single file change with clear fix

5. Handling complex issues

Issues with dependencies:

• Check if blocking issues are resolved
• Note dependencies in your plan
• Consider implementing in phases

Issues with multiple related issues:

• Reference related issues in the plan
• Coordinate if changes overlap
• Consider whether to batch or separate PRs

6. Confirm before implementing

Ask: "Would you like me to start working on this now?"

Wait for confirmation.

Phase 2: Implement

Write the code changes as planned. Test locally.

Follow the repository's coding standards and conventions.

Phase 3: Submit

1. Commit changes

From the worktree (already on the correct branch):

git add -A
git commit -m "Brief description

Closes #$ISSUE_NUMBER"

2. Push and create PR

git push -u origin HEAD
gh pr create --title "Brief description" --body-file templates/pr-body.md

Or use the automated script:

scripts/create-pr.sh $ISSUE_NUMBER "Brief description"

3. Verify linking

Confirm the PR shows

Closes #N

Quick Reference

Closes #N

Fixes #N

Resolves #N

Ref #N

Scripts Reference

scripts/setup-worktree.sh

scripts/load-issue.sh

scripts/create-pr.sh

Subagent Usage

Use subagents to offload codebase exploration from the main context.

Phase 1: Explore Agent for Codebase Analysis

After loading issue context, launch an Explore agent to find relevant files without bloating main context:

Launch Explore agent:
"Find all files related to issue #{number}: {issue_title}

Issue description:
{issue_body}

Search for:
1. Files explicitly mentioned in the issue
2. Files matching keywords from the issue title and body
3. Similar existing implementations (if this is a new feature)
4. Test files that cover the affected areas
5. Configuration files that might need updates
6. Related type definitions or interfaces

For each relevant file found:
- Explain why it's relevant
- Note the key functions/classes to modify
- Identify integration points with other code

Return:
- List of affected files with explanations
- Existing patterns to follow
- Test files to update or add
- Potential side effects to consider"

Benefits:

• Codebase exploration stays out of main context
• Agent can do thorough search without token pressure
• Main context receives concise summary of findings

Phase 1: Plan Agent for Implementation Design

After exploration, optionally launch a Plan agent for complex issues:

Launch Plan agent:
"Design implementation for issue #{number}: {issue_title}

Context from exploration:
{exploration_results}

Issue requirements:
{issue_body}

Create a detailed implementation plan covering:
1. Root cause analysis (for bugs) or feature breakdown (for features)
2. Step-by-step implementation order
3. Testing approach
4. Risks and edge cases
5. Complexity assessment"

When to use Plan agent:

• Complex issues requiring architectural decisions
• Issues touching > 5 files
• Features with multiple valid approaches

Phase 3: Background PR Creation (Optional)

For straightforward PRs, create in background while reporting to user:

Launch background agent:
"Create PR for issue #{number}.
Branch: {branch_name}
Title: {pr_title}
Body: {pr_body}

Steps:
1. git push -u origin HEAD
2. gh pr create --title '...' --body '...'
3. Return PR URL"

User sees immediate confirmation while PR creates in background.

When to use subagents:

• Issue mentions multiple files or areas: Use Explore agent
• Complex architectural issue: Use Plan agent
• User wants quick feedback: Use background PR creation

When to skip subagents:

• Issue clearly specifies exact file and change needed
• Single-line fix or typo correction
• You already know the codebase well from context

Related Skills

• cleanup-issue: Clean up after PR is merged
• pr-feedback-workflow: Address review comments on the PR