Fix GitHub Issue

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

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:

• Checkout main and pull latest changes
• Create a new worktree at .worktrees/issue-$ISSUE_NUMBER
• Create and checkout a branch issue-$ISSUE_NUMBER
• Change into the worktree directory

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

Note: The script auto-adds .worktrees/ to .gitignore.

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

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

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 and the issue appears in the Development sidebar.

Quick Reference

Scripts Reference