/smart-fix

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 (error signature, root cause, fix strategy) and ask:

Issue analysis complete. Please review:
- .smart-fix/01-error-analysis.md (error context)
- .smart-fix/02-root-cause.md (root cause and fix strategy)

Root cause: [brief summary]
Recommended fix: [brief summary]

1. Approve — proceed to deep investigation and fix
2. Request changes — tell me what to adjust
3. Pause — save progress and stop here

Do NOT proceed to Phase 2 until the user selects option 1. If they select option 2, revise and re-checkpoint. If option 3, update state.json status and stop.

---

Phase 2: Deep Investigation (Steps 3-4)

Step 3: Deep Code Analysis

Read .smart-fix/01-error-analysis.md and .smart-fix/02-root-cause.md.

Use the Task tool to launch the debugger agent:

Task:
  subagent_type: "incident-response-debugger"
  description: "Deep code analysis for: $ISSUE"
  prompt: |
    Perform deep code analysis and bisect investigation:

    Context from Phase 1:
    [Insert contents of .smart-fix/02-root-cause.md]

    Deliverables:
    1. Code path analysis: trace execution from entry point to failure
    2. Variable state tracking: values at key decision points
    3. Control flow analysis: branches taken, loops, async operations
    4. Git bisect automation: create bisect script to identify exact breaking commit
    5. Dependency compatibility matrix: version combinations that work/fail
    6. Configuration analysis: environment variables, feature flags, deployment configs
    7. Timing and race condition analysis: async operations, event ordering, locks
    8. Memory and resource analysis: leaks, exhaustion, contention

    Provide structured output with: CODE_PATH, STATE_AT_FAILURE, BISECT_RESULT,
    DEPENDENCY_ISSUES, CONFIGURATION_DRIFT, RACE_CONDITIONS, ISOLATION_VERIFICATION.

Save output to .smart-fix/03-deep-analysis.md.

Update state.json: set current_step to 4, add step 3 to completed_steps.

Step 4: Code Review Deep Dive

Read .smart-fix/02-root-cause.md and .smart-fix/03-deep-analysis.md.

Use the Task tool to launch the code reviewer agent:

Task:
  subagent_type: "incident-response-code-reviewer"
  description: "Review code logic for: $ISSUE"
  prompt: |
    Review code logic and identify design issues:

    Context from Deep Analysis:
    [Insert contents of .smart-fix/03-deep-analysis.md]

    Deliverables:
    1. Logic flaw analysis: incorrect assumptions, missing edge cases, wrong algorithms
    2. Type safety gaps: where stronger types could prevent the issue
    3. Error handling review: missing try-catch, unhandled promises, panic scenarios
    4. Contract validation: input validation gaps, output guarantees not met
    5. Architectural issues: tight coupling, missing abstractions, layering violations
    6. Similar patterns: other code locations with same vulnerability
    7. Fix design: minimal change vs refactoring vs architectural improvement

    Review checklist:
    - Are null/undefined values handled correctly?
    - Are async operations properly awaited/chained?
    - Are error cases explicitly handled?
    - Are type assertions safe?
    - Are API contracts respected?
    - Are side effects isolated?

    Provide structured output with: LOGIC_FLAWS, TYPE_SAFETY_GAPS, ERROR_HANDLING_GAPS,
    SIMILAR_VULNERABILITIES, FIX_DESIGN, REFACTORING_OPPORTUNITIES, ARCHITECTURAL_CONCERNS.

Save output to .smart-fix/04-code-review.md.

Update state.json: set current_step to 5, add step 4 to completed_steps.

---

Phase 3: Fix Implementation (Step 5)

Step 5: Implement Fix

Read .smart-fix/02-root-cause.md, .smart-fix/03-deep-analysis.md, and .smart-fix/04-code-review.md.

Route to the appropriate agent based on the codebase language. Use general-purpose with role context for language-specific fixes:

Task:
  subagent_type: "general-purpose"
  description: "Implement fix for: $ISSUE"
  prompt: |
    You are a senior software engineer. Implement a production-safe fix with comprehensive test coverage.

    Context from investigation:
    - Root cause: [Insert from .smart-fix/02-root-cause.md]
    - Code review: [Insert from .smart-fix/04-code-review.md]

    Deliverables:
    1. Minimal fix implementation addressing root cause (not symptoms)
    2. Unit tests: specific failure case reproduction, edge cases, error paths
    3. Integration tests: end-to-end scenarios with real dependencies
    4. Regression tests: tests for similar vulnerabilities found in code review
    5. Production-safe practices:
       - Feature flags for gradual rollout
       - Graceful degradation if fix fails
       - Structured logging for debugging
       - Monitoring hooks for fix verification

    Implementation requirements:
    - Follow existing code patterns and conventions
    - Add strategic debug logging (JSON structured logs)
    - Include comprehensive type annotations
    - Update error messages to be actionable
    - Maintain backward compatibility

    Report: FIX_SUMMARY, CHANGED_FILES, NEW_FILES, TEST_COVERAGE, TEST_RESULTS,
    BREAKING_CHANGES, OBSERVABILITY_ADDITIONS, BACKWARD_COMPATIBILITY.

Save output to .smart-fix/05-implementation.md.

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

---

PHASE CHECKPOINT 2 — User Approval Required

Display a summary of the fix from .smart-fix/05-implementation.md and ask:

Fix implementation complete. Please review .smart-fix/05-implementation.md

Changes: [summary of files changed]
Tests: [summary of test coverage]
Breaking changes: [none or details]

1. Approve — proceed to verification
2. Request changes — tell me what to adjust
3. Pause — save progress and stop here

Do NOT proceed to Phase 4 until the user approves.

---

Phase 4: Verification (Steps 6-8)

Step 6: Regression Testing

Read .smart-fix/05-implementation.md.

Use the Task tool to launch the test automator:

Task:
  subagent_type: "incident-response-test-automator"
  description: "Regression testing for: $ISSUE fix"
  prompt: |
    Run comprehensive regression testing and verify fix quality:

    Context:
    [Insert contents of .smart-fix/05-implementation.md]

    Deliverables:
    1. Full test suite execution: unit, integration, end-to-end, contract tests
    2. Regression detection: compare results before/after, identify new failures
    3. Test quality assessment: coverage metrics, test determinism
    4. Security testing: auth checks, input validation, injection prevention
    5. Cross-environment testing: staging/QA validation

    Report: TEST_RESULTS, CODE_COVERAGE, REGRESSION_DETECTED, SECURITY_SCAN, TEST_QUALITY.

Step 7: Performance Validation

Read .smart-fix/05-implementation.md.

Launch in parallel with Step 6:

Task:
  subagent_type: "general-purpose"
  description: "Performance validation for: $ISSUE fix"
  prompt: |
    You are a performance engineer. Measure performance impact and validate no regressions.

    Context:
    [Insert contents of .smart-fix/05-implementation.md]

    Deliverables:
    1. Performance benchmarks: response time (p50, p95, p99), throughput, resource utilization
    2. Comparison with baseline: before/after metrics
    3. Load testing: stress test, soak test for memory leaks, spike test
    4. APM analysis: distributed trace analysis, slow query detection, N+1 patterns
    5. Production readiness: capacity planning impact, scaling characteristics

    Report: PERFORMANCE_BASELINE, PERFORMANCE_AFTER_FIX, PERFORMANCE_IMPACT,
    LOAD_TEST_RESULTS, APM_INSIGHTS, PRODUCTION_READY.

Step 8: Security Review

Read .smart-fix/05-implementation.md.

Launch in parallel with Steps 6-7:

Task:
  subagent_type: "general-purpose"
  description: "Security review for: $ISSUE fix"
  prompt: |
    You are a security auditor. Review the fix for security vulnerabilities.

    Context:
    [Insert contents of .smart-fix/05-implementation.md]

    Review for: OWASP Top 10, authentication/authorization flaws, input validation gaps,
    data protection issues, dependency vulnerabilities, and security anti-patterns.

    Provide findings with severity, location, and specific fix recommendations.

After all three complete, consolidate into .smart-fix/06-verification.md:

# Verification: $ISSUE

## Test Results

[Summary from Step 6]

## Performance Validation

[Summary from Step 7]

## Security Review

[Summary from Step 8]

## Action Items

[Critical/high findings that need addressing]

If there are Critical or High severity findings, address them before proceeding.

Update state.json: set current_step to "checkpoint-3", add steps 6-8 to completed_steps.

---

PHASE CHECKPOINT 3 — User Approval Required

Display verification results from .smart-fix/06-verification.md and ask:

Verification complete. Please review .smart-fix/06-verification.md

Test results: [pass/fail summary]
Performance impact: [improved/neutral/degraded]
Security findings: [X critical, Y high, Z medium]

1. Approve — proceed to final review and documentation
2. Request changes — tell me what to fix
3. Pause — save progress and stop here

Do NOT proceed to Phase 5 until the user approves.

---

Phase 5: Final Review & Prevention (Steps 9-10)

Step 9: Final Code Review

Read .smart-fix/05-implementation.md and .smart-fix/06-verification.md.

Task:
  subagent_type: "incident-response-code-reviewer"
  description: "Final review for: $ISSUE fix"
  prompt: |
    Perform final code review and approve for deployment:

    Implementation: [Insert contents of .smart-fix/05-implementation.md]
    Verification: [Insert contents of .smart-fix/06-verification.md]

    Deliverables:
    1. Code quality review: conventions, patterns, error handling, observability
    2. Architecture review: boundaries, coupling, scalability
    3. Security review: vulnerabilities, validation, auth
    4. Deployment readiness: rollback plan, feature flags, monitoring
    5. Risk assessment: blast radius, rollout strategy, success metrics

    Report: REVIEW_STATUS, DEPLOYMENT_RISK, ROLLBACK_PLAN, ROLLOUT_STRATEGY,
    MONITORING_REQUIREMENTS, FINAL_VERDICT.

Save output to .smart-fix/07-final-review.md.

Update state.json: set current_step to 10, add step 9 to completed_steps.

Step 10: Documentation & Prevention

Read all .smart-fix/*.md files.

Task:
  subagent_type: "general-purpose"
  description: "Document fix and prevention for: $ISSUE"
  prompt: |
    You are a technical writer and SRE specialist. Document the fix and implement prevention strategies.

    Context:
    [Insert contents of all .smart-fix/*.md files]

    Deliverables:
    1. Code documentation: inline comments for non-obvious logic, function docs
    2. Operational documentation: CHANGELOG entry, release notes, runbook entry
    3. Prevention through static analysis: linting rules, stricter type checking
    4. Monitoring and alerting: error rate alerts, custom metrics, SLO dashboards
    5. Architectural improvements: similar vulnerability patterns, refactoring proposals
    6. Postmortem document (if high-severity): timeline, root cause, action items

    Report: DOCUMENTATION_UPDATES, PREVENTION_MEASURES, MONITORING_ADDED,
    ARCHITECTURAL_IMPROVEMENTS, SIMILAR_VULNERABILITIES, FOLLOW_UP_TASKS.

Save output to .smart-fix/08-prevention.md.

Update state.json: set current_step to "complete", add step 10 to completed_steps.

---

Completion

Update state.json:

• Set status to "complete"
• Set last_updated to current timestamp

Present the final summary:

Issue resolution complete: $ISSUE

## Files Created
[List all .smart-fix/ output files]

## Resolution Summary
- Error Analysis: .smart-fix/01-error-analysis.md
- Root Cause: .smart-fix/02-root-cause.md
- Deep Analysis: .smart-fix/03-deep-analysis.md
- Code Review: .smart-fix/04-code-review.md
- Implementation: .smart-fix/05-implementation.md
- Verification: .smart-fix/06-verification.md
- Final Review: .smart-fix/07-final-review.md
- Prevention: .smart-fix/08-prevention.md

## Next Steps
1. Review all generated code and documentation
2. Run the full test suite to verify everything passes
3. Create a pull request with the implementation
4. Deploy using the rollout strategy in .smart-fix/07-final-review.md
5. Monitor using the alerts configured in .smart-fix/08-prevention.md

Issue to resolve: $ARGUMENTS