Hotfix Workflow

1. Sync main

git checkout main && git pull

2. Create worktree and branch

git worktree add .claude/worktrees/hotfix-<name> -b hotfix/<description>
cd .claude/worktrees/hotfix-<name>

3. Identify and fix

• Read the error carefully — stack trace, logs, error message
• Make the smallest possible change that fixes the issue
• No refactoring, no cleanup, no "while I'm here" improvements

4. Test

• Write a regression test for the bug
• Run full test suite — must pass with zero failures
• If test infrastructure doesn't cover this path, manually verify and document how

5. Create PR

• Commit with message: what broke, why, and what the fix does
• Push and create PR via

  gh pr create

• Mark PR as urgent in the description
• Wait for CI/CD checks to complete:

  gh pr checks <number> --watch

• If checks fail, fix the issues and push again — do not notify the user until all checks are green
• Once all checks pass, return the PR URL and ask the user to review
• DO NOT merge — wait for explicit approval

6. Merge (only when approved)

• gh pr merge <number> --merge

• Clean up worktree:

  cd <project-root> && git worktree remove .claude/worktrees/hotfix-<name>

• git checkout main && git pull && git branch -d hotfix/<description>

• Consider whether a release is needed immediately

Rules

• Scope discipline — fix ONLY the bug, nothing else
• Never merge without explicit approval
• Never push directly to main
• Always write a regression test
• If the fix is complex (>20 lines changed), switch to

  /fix-bug

  workflow instead