Fix

Workflow orchestrator for bug investigation and resolution. Chains specialized skills based on issue scope.

Usage

/fix <scope> [options] [description]

Question Flow (No Arguments)

If the user types just /fix with no or partial arguments, guide them through this question flow. Use AskUserQuestion for each phase.

Phase 0: Workflow Selection

question: "What would you like to fix?"
header: "Fix type"
options:
  - label: "Help me choose (Recommended)"
    description: "I'll ask questions to pick the right fix workflow"
  - label: "Bug - something is broken"
    description: "Chain: investigate → diagnose → implement → test → commit"
  - label: "Hook - Claude Code hook issue"
    description: "Chain: debug-hooks → hook-developer → implement → test"
  - label: "Dependencies - import/package errors"
    description: "Chain: preflight → research → plan → implement → qlty-check"
  - label: "PR Comments - address reviewer feedback"
    description: "Chain: github-search → research → plan → implement → commit"

Mapping:

• "Help me choose" → Continue to Phase 1-4 questions
• "Bug" → Set scope=bug, skip to Phase 2 (issue details)
• "Hook" → Set scope=hook, skip to Phase 2 (issue details)
• "Dependencies" → Set scope=deps, skip to Phase 2 (issue details)
• "PR Comments" → Set scope=pr-comments, skip to Phase 2 (issue details)

If Answer is Unclear (via "Other"):

question: "I want to understand what kind of fix you need. Did you mean..."
header: "Clarify"
options:
  - label: "Help me choose"
    description: "Not sure - guide me through questions"
  - label: "Bug - something is broken"
    description: "Code isn't working as expected"
  - label: "Hook - Claude Code hook issue"
    description: "Hooks not firing or producing wrong output"
  - label: "Neither - let me explain differently"
    description: "I'll describe my issue"

Phase 1: Issue Type

question: "What kind of issue are you dealing with?"
header: "Issue type"
options:
  - label: "Something is broken/not working"
    description: "Bug in the code"
  - label: "Claude Code hook not firing"
    description: "Hook-specific debugging"
  - label: "Import/dependency errors"
    description: "Package or module issues"
  - label: "Need to address PR feedback"
    description: "Reviewer comments to fix"

Mapping:

• "Something broken" → bug scope
• "Hook not firing" → hook scope
• "Import errors" → deps scope
• "PR feedback" → pr-comments scope

Phase 2: Issue Details

question: "Can you describe the issue?"
header: "Details"
options: []  # Free text - user describes the problem

Capture the error message, unexpected behavior, or PR link.

Phase 3: Investigation Depth

question: "How should I investigate?"
header: "Investigation"
options:
  - label: "Diagnose and fix"
    description: "Find the problem and implement a fix"
  - label: "Diagnose only (dry run)"
    description: "Just tell me what's wrong, don't change code"
  - label: "Quick fix"
    description: "I know the issue, just fix it fast"

Mapping:

• "Diagnose only" → --dry-run
• "Quick fix" → skip investigation, go straight to spark agent

Phase 4: Testing & Commit

question: "After fixing, should I..."
header: "After fix"
multiSelect: true
options:
  - label: "Write a regression test"
    description: "Prevent this bug from recurring"
  - label: "Commit the fix"
    description: "Create a git commit"
  - label: "Just fix, nothing else"
    description: "I'll handle tests and git"

Mapping:

• No "regression test" → --no-test
• No "commit" → --no-commit

Summary Before Execution

Based on your answers, I'll run:

**Scope:** bug
**Issue:** "Login button not responding on Safari"
**Chain:** sleuth (investigate) → spark (fix) → arbiter (test) → commit
**Options:** (none)

Proceed? [Yes / Adjust settings]

Scopes

Options

Workflow

Phase 1: Parse Arguments

# Parse scope and options
SCOPE="${1:-bug}"
NO_TEST=false
DRY_RUN=false
NO_COMMIT=false

for arg in "$@"; do
  case $arg in
    --no-test) NO_TEST=true ;;
    --dry-run) DRY_RUN=true ;;
    --no-commit) NO_COMMIT=true ;;
  esac
done

Phase 2: Investigation (Parallel)

Spawn sleuth agent for parallel investigation:

Task(
  subagent_type="sleuth",
  prompt="""
  Investigate this issue in parallel:

  1. **Logs**: Check recent logs for errors
     - Application logs
     - System logs if relevant
     - Build/test output

  2. **Database State** (if applicable):
     - Check for stuck/invalid records
     - Verify schema matches expectations

  3. **Git State**:
     - Recent commits that might relate
     - Uncommitted changes
     - Current branch context

  4. **Runtime State**:
     - Running processes
     - Port conflicts
     - Environment variables

  Issue description: {user_description}

  Return structured findings with evidence.
  """
)

Phase 3: Diagnosis Report

Present findings to user:

## Diagnosis Report

### Scope: {scope}

### Evidence Found

**Logs:**
- [Finding with timestamp/line reference]

**Database:**
- [Finding with table/query reference]

**Git State:**
- [Recent relevant commits]
- [Uncommitted changes]

**Runtime:**
- [Process/port findings]

### Root Cause Analysis

**Primary Hypothesis:** [Most likely cause based on evidence]

**Supporting Evidence:**
1. [Evidence 1]
2. [Evidence 2]

**Alternative Hypotheses:**
- [Alternative 1]: [Why less likely]

### Proposed Fix

**Approach:** [How to fix]

**Files to Modify:**
- `path/to/file.ts:123` - [Change description]

**Risk Assessment:** [Low/Medium/High] - [Why]

---

**Proceed with fix?** (yes/no/modify approach)

Phase 4: Human Checkpoint (Diagnosis)

REQUIRED: Wait for user confirmation before implementing.