/smart-fix

description: "Intelligent issue resolution with multi-agent debugging, root cause analysis, and verified fix implementation"
argument-hint: "<issue description> [--verification minimal|standard|comprehensive] [--prevention none|immediate|comprehensive]"

Intelligent Issue Resolution Orchestrator

CRITICAL BEHAVIORAL RULES

You MUST follow these rules exactly. Violating any of them is a failure.

1. **Execute steps in order.** Do NOT skip ahead, reorder, or merge steps. 2. **Write output files.** Each step MUST produce its output file in `.smart-fix/` before the next step begins. Read from prior step files — do NOT rely on context window memory. 3. **Stop at checkpoints.** When you reach a `PHASE CHECKPOINT`, you MUST stop and wait for explicit user approval before continuing. Use the AskUserQuestion tool with clear options. 4. **Halt on failure.** If any step fails (agent error, test failure, missing dependency), STOP immediately. Present the error and ask the user how to proceed. Do NOT silently continue. 5. **Use only local agents.** All `subagent_type` references use agents bundled with this plugin or `general-purpose`. No cross-plugin dependencies. 6. **Never enter plan mode autonomously.** Do NOT use EnterPlanMode. This command IS the plan — execute it.

Pre-flight Checks

Before starting, perform these checks:

1. Check for existing session

Check if `.smart-fix/state.json` exists:

• If it exists and `status` is `"in_progress"`: Read it, display the current step, and ask the user:

  Found an in-progress smart-fix session:
  Issue: [issue from state]
  Current step: [step from state]

  1. Resume from where we left off
  2. Start fresh (archives existing session)

• If it exists and `status` is `"complete"`: Ask whether to archive and start fresh.

2. Initialize state

Create `.smart-fix/` directory and `state.json`:

{
  "issue": "$ARGUMENTS",
  "status": "in_progress",
  "verification_level": "standard",
  "prevention_focus": "immediate",
  "current_step": 1,
  "current_phase": 1,
  "completed_steps": [],
  "files_created": [],
  "started_at": "ISO_TIMESTAMP",
  "last_updated": "ISO_TIMESTAMP"
}

Parse `$ARGUMENTS` for `--verification` and `--prevention` flags. Use defaults if not specified.

3. Parse issue description

Extract the issue description from `$ARGUMENTS` (everything before the flags). This is referenced as `$ISSUE` in prompts below.

---

Phase 1: Issue Analysis (Steps 1-2)

Step 1: Error Detection and Context Gathering

Use the Task tool to launch the error detective agent:

Task:
  subagent_type: "incident-response-error-detective"
  description: "Analyze error context for: $ISSUE"
  prompt: |
    Analyze error traces, logs, and observability data for: $ISSUE

    Deliverables:
    1. Error signature analysis: exception type, message patterns, frequency, first occurrence
    2. Stack trace deep dive: failure location, call chain, involved components
    3. Reproduction steps: minimal test case, environment requirements, data fixtures needed
    4. Observability context:
       - Sentry/DataDog error groups and trends
       - Distributed traces showing request flow (OpenTelemetry/Jaeger)
       - Structured logs (JSON logs with correlation IDs)
       - APM metrics: latency spikes, error rates, resource usage
    5. User impact assessment: affected user segments, error rate, business metrics impact
    6. Timeline analysis: when did it start, correlation with deployments/config changes
    7. Related symptoms: similar errors, cascading failures, upstream/downstream impacts

    Modern debugging techniques to employ:
    - AI-assisted log analysis (pattern detection, anomaly identification)
    - Distributed trace correlation across microservices
    - Production-safe debugging (no code changes, use observability data)
    - Error fingerprinting for deduplication and tracking

    Provide structured output with: ERROR_SIGNATURE, FREQUENCY, FIRST_SEEN, STACK_TRACE,
    REPRODUCTION, OBSERVABILITY_LINKS, USER_IMPACT, TIMELINE, RELATED_ISSUES.

Save the agent's output to `.smart-fix/01-error-analysis.md`.

Update `state.json`: set `current_step` to 2, add step 1 to `completed_steps`.

Step 2: Root Cause Identification

Read `.smart-fix/01-error-analysis.md` to load error context.

Use the Task tool to launch the debugger agent:

Task:
  subagent_type: "incident-response-debugger"
  description: "Identify root cause for: $ISSUE"
  prompt: |
    Perform root cause investigation using error-detective output:

    Context from Error-Detective:
    [Insert full contents of .smart-fix/01-error-analysis.md]

    Deliverables:
    1. Root cause hypothesis with supporting evidence
    2. Code-level analysis: variable states, control flow, timing issues
    3. Git bisect analysis: identify introducing commit (automate with git bisect run)
    4. Dependency analysis: version conflicts, API changes, configuration drift
    5. State inspection: database state, cache state, external API responses
    6. Failure mechanism: why does the code fail under these specific conditions
    7. Fix strategy options with tradeoffs (quick fix vs proper fix)

    Context needed for next phase:
    - Exact file paths and line numbers requiring changes
    - Data structures or API contracts affected
    - Dependencies that may need updates
    - Test scenarios to verify the fix
    - Performance characteristics to maintain

    Provide structured output with: ROOT_CAUSE, INTRODUCING_COMMIT, AFFECTED_FILES,
    FAILURE_MECHANISM, DEPENDENCIES, FIX_STRATEGY, TESTING_REQUIREMENTS.

Save the agent's output to `.smart-fix/02-root-cause.md`.

Update `state.json`: set `current_step` to "checkpoint-1", add step 2 to `completed_steps`.

---

PHASE CHECKPOINT 1 — User Approval Required

You MUST stop here and present findings for review.

Display a summary from `.smart-fix/01-error-analysis.md` and `.smart-fix/02-root-cause.md`