fix-bug

Bug Fix Workflow

This workflow is MANDATORY. Follow every step in order. If any required command/skill fails with "Unknown skill", STOP and alert the user.

Required Plugins

This workflow requires the following plugins to be installed AND enabled:

Plugin	Skills/Commands Used
superpowers@claude-plugins-official	/superpowers:systematic-debugging, /superpowers:brainstorming, /superpowers:writing-plans, /superpowers:subagent-driven-development (default executor), /superpowers:executing-plans (headless mode)
pr-review-toolkit@claude-plugins-official	code-simplifier agent, code-reviewer agent, /pr-review-toolkit:review-pr

To enable plugins, add to ~/.claude/settings.json:

{
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true,
    "pr-review-toolkit@claude-plugins-official": true,
    "frontend-design@claude-plugins-official": true
  }
}

---

Pre-Flight Checks

1. Create Isolated Workspace (MANDATORY)

Check if already in a worktree:

if [[ "$(pwd)" == *".worktrees/"* ]]; then
  echo "STATE: ALREADY_IN_WORKTREE"
else
  echo "STATE: NEEDS_WORKTREE"
fi

If ALREADY_IN_WORKTREE:

• You're already isolated — continue with current workspace
• Surface drift on the parent default branch (advisory; no auto-FF from inside a worktree)

# DRIFT-PREFLIGHT-ALREADY-BEGIN (byte-identical with commands/fix-bug.md — enforced by test-contracts.sh)
ROOT="$(git rev-parse --show-toplevel)"
LIB="$ROOT/.claude/hooks/lib/default-branch.sh"
[ ! -f "$LIB" ] && LIB="$ROOT/hooks/lib/default-branch.sh"
DEFAULT_BRANCH=$(bash "$LIB" 2>/dev/null) \
    || { DEFAULT_BRANCH="main"; echo "  ⚠ default-branch helper bailed; assuming 'main' (drift check may be wrong on non-main repos)" >&2; }
ALREADY_FETCH_OK=true
git fetch origin --quiet 2>/dev/null || ALREADY_FETCH_OK=false
# Behind-check: only if FETCH succeeded AND both refs exist. Skipping on fetch failure
# prevents reporting drift against a stale origin/* ref. Also guards rev-list exit-128.
if [ "$ALREADY_FETCH_OK" = "true" ] \
   && git rev-parse --verify "$DEFAULT_BRANCH" >/dev/null 2>&1 \
   && git rev-parse --verify "origin/$DEFAULT_BRANCH" >/dev/null 2>&1; then
  BEHIND=$(git rev-list --count "$DEFAULT_BRANCH..origin/$DEFAULT_BRANCH" 2>/dev/null || echo "")
  if [[ "$BEHIND" =~ ^[0-9]+$ ]] && [ "$BEHIND" -gt 0 ]; then
    echo "  ⚠ Parent '$DEFAULT_BRANCH' is $BEHIND commits behind origin (skipping auto-FF from worktree)"
  fi
fi
# DRIFT-PREFLIGHT-ALREADY-END