fix-issue

name	fix-issue
description	Start work on a GitHub issue — verify a clean workspace, read the issue, branch off the correct base (the branch where the fix will ship) as issue-<nr>-<short-description>, then plan the implementation. Use when the user says "fix issue 123", "work on issue
allowed-tools	Bash, Read, Glob, Grep, WebFetch

Start Work on a GitHub Issue

Prepares a clean, correctly-branched workspace for a GitHub issue, then either implements a trivial fix directly or produces a plan when the solution is open.

The issue is given as an argument: a bare number (123), a #-prefixed number (#123), or a full GitHub URL. Extract the number. If no argument was given, ask the user which issue to work on before doing anything else.

This repository has several remotes; origin is haumacher/phoneblock. Always target origin explicitly — never assume a single remote.

Step 1 — Ensure the workspace is clean

Run git status --porcelain.

• Clean (no output): continue to step 2.
• Not clean: do not proceed. Run git status and git diff --stat (plus git stash list if relevant), describe the uncommitted/untracked changes to the user, and ask what to do with them (e.g. commit, stash, discard, or proceed on a branch from the current commit). Wait for the answer before continuing — never stash, commit, or discard on your own initiative.

Step 2 — Read the issue

gh issue view <nr> --repo haumacher/phoneblock --comments

Read the title, body, and comments so you understand what is actually being asked. If the issue is closed or cannot be found, stop and tell the user.

Step 3 — Fetch the current state

git fetch origin --tags

This makes every up-to-date base candidate (all origin/* branches and tags) available locally before the branch is created.

Step 4 — Create and switch to the issue branch

Create the branch before investigating any code. Analysing the repository at whatever commit happens to be checked out is meaningless — you must first be on the base where the fix will actually ship, then study that code. So decide the base branch now, from the issue alone; do not open source files to make this choice.

Pick the base branch = where the fix will ship. Usually this is origin/master. But some work ships on a maintenance or release line and must branch from there instead — for example dongle firmware fixes destined for a release branch off dongle-X.Y.x (or its rc tag), per CLAUDE.md's Dongle Release Branches policy. Determine the target from the issue: which component it touches and which release it is meant for. If the correct base is not obvious (e.g. it could be master or a release line), ask the user before branching — do not default to origin/master silently.

Derive a short, kebab-case description (~3–5 words, lowercase, ASCII) from the issue title. Branch name schema:

issue-<nr>-<short-description>

Example: issue 142 "CardDAV sync fails for long contact names" → issue-142-carddav-long-contact-names.

Create the branch from the chosen base and switch to it (substitute the base you picked for <base>, e.g. origin/master or dongle-1.4.x):

git checkout -b issue-<nr>-<short-description> <base>

If a branch with that name already exists, mention it and ask the user whether to reuse it, pick a different suffix, or replace it.

Step 5 — Decide: implement directly or plan

Investigate the codebase as needed (CLAUDE.md describes the module layout) and judge how clear-cut the fix is:

• Trivial / unambiguous — small change with one obvious correct solution (typo, clear bug with a single fix, a well-specified minor feature). Implement it directly, then verify (build/tests as appropriate) and report the result. No need to ask first.
• Open or non-trivial — the change is large, touches many areas, or there are several plausible solution alternatives with real trade-offs. Produce a concrete implementation plan (which files change, the approach chosen, alternatives considered, open questions), present it with ExitPlanMode, and wait for approval before editing files.

When in doubt between the two, prefer planning and asking.