Claude-Code-Workflow/.claude/commands/workflow/lite-fix.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
lite-fix	Lightweight bug diagnosis and fix workflow with fast-track verification and optional hotfix mode for production incidents	[--critical|--hotfix] [--incident ID] "bug description or issue reference"	TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*), Read(*), Bash(*)

Workflow Lite-Fix Command (/workflow:lite-fix)

Overview

Fast-track bug fixing workflow optimized for quick diagnosis, targeted fixes, and streamlined verification. Supports both regular bug fixes and critical production hotfixes with appropriate process adaptations.

Core capabilities:

• Rapid root cause diagnosis with intelligent code search
• Impact scope assessment (affected users, data, systems)
• Fix strategy selection (immediate patch vs comprehensive refactor)
• Risk-aware verification (smoke tests for hotfix, full suite for regular)
• Automatic hotfix branch management
• Follow-up task generation for comprehensive fixes

Usage

Command Syntax

/workflow:lite-fix [FLAGS] <BUG_DESCRIPTION>

# Flags
--critical, -c             Critical bug requiring fast-track process
--hotfix, -h               Production hotfix mode (creates hotfix branch)
--incident <ID>            Associate with incident tracking ID

# Arguments
<bug-description>          Bug description or issue reference (required)

Severity Modes

Mode	Time Budget	Use Case	Workflow Characteristics
Regular (default)	2-4 hours	Non-blocking bugs, <20% user impact	Full diagnosis + comprehensive testing
Critical (--critical)	30-60 min	Core feature degraded, 20-50% user impact	Focused diagnosis + key scenario testing
Hotfix (--hotfix)	15-30 min	Production outage, 100% user impact	Minimal diagnosis + smoke testing + auto follow-up

Examples

# Regular mode: Standard bug fix
/workflow:lite-fix "User avatar upload fails with 413 error"

# Critical mode: Urgent but not fatal
/workflow:lite-fix --critical "Shopping cart randomly loses items at checkout"

# Hotfix mode: Production incident
/workflow:lite-fix --hotfix --incident INC-2024-1015 "Payment gateway 5xx errors"

Execution Process

Workflow Overview

Bug Input → Diagnosis (Phase 1) → Impact Assessment (Phase 2)
        ↓
    Fix Planning (Phase 3) → Verification Strategy (Phase 4)
        ↓
    User Confirmation (Phase 5) → Execution (Phase 6)

Phase Summary

Phase	Regular	Critical	Hotfix
1. Diagnosis	Full (cli-explore-agent)	Focused (direct grep)	Minimal (known issue)
2. Impact	Comprehensive	Targeted	Critical path only
3. Planning	Multiple strategies	Single best	Surgical fix
4. Verification	Full test suite	Key scenarios	Smoke tests
5. Confirmation	4 dimensions	3 dimensions	2 dimensions
6. Execution	Via lite-execute	Via lite-execute	Via lite-execute + monitoring

---

Detailed Phase Execution

Phase 1: Diagnosis & Root Cause Analysis

Goal: Identify root cause and affected code paths

Execution Strategy by Mode:

Regular Mode - Comprehensive search:

Task(
  subagent_type="cli-explore-agent",
  prompt=`
  Bug: ${bug_description}

  Execute diagnostic search:
  1. Search error message: Grep "${error}" --output_mode content
  2. Find related code: Glob "**/affected-module/**/*.{ts,js}"
  3. Trace execution path
  4. Check recent changes: git log --since="1 week ago"

  Return: Root cause hypothesis, affected paths, reproduction steps
  Time limit: 20 minutes
  `
)

Critical Mode - Direct targeted search:

grep -r '${error_message}' src/ --include='*.ts' -n | head -10
git log --oneline --since='1 week ago' -- '*affected*' | head -5
git blame ${suspected_file}

Hotfix Mode - Minimal search (assume known issue):

Read(suspected_file)  # User provides file path

Output Structure:

{
  root_cause: {
    file: "src/auth/tokenValidator.ts",
    line_range: "45-52",
    issue: "Token expiration check uses wrong comparison",
    introduced_by: "commit abc123"
  },
  reproduction_steps: ["Login", "Wait 15min", "Access protected route"],
  affected_scope: {
    users: "All authenticated users",
    features: ["login", "API access"],
    data_risk: "none"
  }
}

TodoWrite: Mark Phase 1 completed, Phase 2 in_progress

---

Phase 2: Impact Assessment

Goal: Quantify blast radius and risk level

Risk Score Calculation:

risk_score = (user_impact × 0.4) + (system_risk × 0.3) + (business_impact × 0.3)

// Severity mapping
if (risk_score >= 8.0) severity = "critical"
else if (risk_score >= 5.0) severity = "high"
else if (risk_score >= 3.0) severity = "medium"
else severity = "low"

Assessment Output:

{
  affected_users: {
    count: "5000 active users (100%)",
    severity: "high",
    workaround: "Re-login required"
  },
  system_risk: {
    availability: "degraded_30%",
    cascading_failures: "possible_logout_storm"
  },
  business_impact: {
    revenue: "medium",
    reputation: "high",
    sla_breach: "yes"
  },
  risk_score: 7.1,
  severity: "high"
}

Auto-Severity Suggestion: If risk_score >= 8.0 and user didn't provide --critical, suggest:

💡 Suggestion: Consider using --critical flag (risk score: 8.2/10)

TodoWrite: Mark Phase 2 completed, Phase 3 in_progress

---

Phase 3: Fix Planning & Strategy Selection

Goal: Generate fix options with trade-off analysis

Strategy Generation by Mode:

Regular Mode - Multiple strategies (1-3 options):

[
  {
    strategy: "immediate_patch",
    description: "Fix comparison operator",
    files: ["src/auth/tokenValidator.ts:47"],
    estimated_time: "15 minutes",
    risk: "low",
    pros: ["Quick fix", "Minimal change"],
    cons: ["Doesn't address token refresh"]
  },
  {
    strategy: "comprehensive_refactor",
    description: "Refactor token validation with proper refresh",
    files: ["src/auth/tokenValidator.ts", "src/auth/refreshToken.ts"],
    estimated_time: "2 hours",
    risk: "medium",
    pros: ["Addresses root cause"],
    cons: ["Longer implementation"]
  }
]

Critical/Hotfix Mode - Single best strategy:

{
  strategy: "surgical_fix",
  description: "Minimal change to fix comparison",
  files: ["src/auth/tokenValidator.ts:47"],
  change: "currentTime > expiryTime → currentTime >= expiryTime",
  estimated_time: "5 minutes",
  risk: "minimal"
}

Complexity Assessment & Planning:

complexity = assessComplexity(fix_strategies)

if (complexity === "low" || mode === "hotfix") {
  plan = generateSimplePlan(selected_strategy)  // Direct by Claude
} else if (complexity === "medium") {
  plan = Task(subagent_type="cli-lite-planning-agent", ...)
} else {
  suggestCommand("/workflow:plan --mode bugfix")
}

Plan Output:

{
  summary: "Fix timestamp comparison in token validation",
  approach: "Update comparison operator",
  tasks: [{
    title: "Fix token expiration comparison",
    file: "src/auth/tokenValidator.ts",
    action: "Update",
    implementation: ["Locate validateToken", "Update line 47", "Add comment"],
    verification: ["Manual test at boundary", "Run auth tests"]
  }],
  estimated_time: "30 minutes",
  recommended_execution: "Agent"
}

TodoWrite: Mark Phase 3 completed, Phase 4 in_progress

---

Phase 4: Verification Strategy

Goal: Define testing approach based on severity

Test Strategy Selection:

Mode	Test Scope	Duration	Automation
Regular	Full test suite	10-20 min	npm test
Critical	Focused integration	5-10 min	npm test -- auth.test.ts
Hotfix	Smoke tests	2-5 min	npm test -- auth.smoke.test.ts

Branch Strategy:

Regular/Critical:

{
  type: "feature_branch",
  base: "main",
  name: "fix/token-expiration-edge-case",
  merge_target: "main"
}

Hotfix:

{
  type: "hotfix_branch",
  base: "production_tag_v2.3.1",  // ⚠️ From production tag
  name: "hotfix/token-validation-fix",
  merge_target: ["main", "production"]  // Dual merge
}

TodoWrite: Mark Phase 4 completed, Phase 5 in_progress

---

Phase 5: User Confirmation & Execution Selection

Multi-Dimension Confirmation:

Regular Mode (4 dimensions):

AskUserQuestion({
  questions: [
    {
      question: "Confirm fix approach?",
      header: "Fix Confirmation",
      options: [
        { label: "Proceed", description: "Execute as planned" },
        { label: "Modify", description: "Adjust strategy" },
        { label: "Escalate", description: "Use /workflow:plan" }
      ]
    },
    {
      question: "Execution method:",
      header: "Execution",
      options: [
        { label: "Agent", description: "@code-developer" },
        { label: "CLI Tool", description: "Codex/Gemini" },
        { label: "Manual", description: "Provide plan only" }
      ]
    },
    {
      question: "Verification level:",
      header: "Testing",
      options: [
        { label: "Full Suite", description: "All tests" },
        { label: "Focused", description: "Affected tests" },
        { label: "Smoke Only", description: "Critical path" }
      ]
    },
    {
      question: "Post-fix review:",
      header: "Code Review",
      options: [
        { label: "Gemini", description: "AI review" },
        { label: "Skip", description: "Trust tests" }
      ]
    }
  ]
})

Critical Mode (3 dimensions - skip code review)

Hotfix Mode (2 dimensions - minimal confirmation):

AskUserQuestion({
  questions: [
    {
      question: "Confirm hotfix deployment:",
      options: [
        { label: "Deploy", description: "Apply to production" },
        { label: "Stage First", description: "Test in staging" },
        { label: "Abort", description: "Cancel" }
      ]
    },
    {
      question: "Post-deployment monitoring:",
      options: [
        { label: "Real-time", description: "Monitor 15 minutes" },
        { label: "Passive", description: "Rely on alerts" }
      ]
    }
  ]
})

TodoWrite: Mark Phase 5 completed, Phase 6 in_progress

---

Phase 6: Execution Dispatch & Follow-up

Step 6.1: Dispatch to lite-execute

executionContext = {
  mode: "bugfix",
  severity: mode,  // "regular" | "critical" | "hotfix"
  planObject: plan,
  diagnosisContext: diagnosis,
  impactContext: impact_assessment,
  verificationStrategy: test_strategy,
  branchStrategy: branch_strategy,
  executionMethod: user_selection.execution_method,
  monitoringLevel: user_selection.monitoring
}

SlashCommand("/workflow:lite-execute --in-memory --mode bugfix")

Step 6.2: Hotfix Follow-up Tasks (auto-generated if hotfix mode)

if (mode === "hotfix") {
  follow_up_tasks = [
    {
      id: `FOLLOWUP-${taskId}-comprehensive`,
      title: "Replace hotfix with comprehensive fix",
      priority: "high",
      due_date: "within_3_days"
    },
    {
      id: `FOLLOWUP-${taskId}-postmortem`,
      title: "Incident postmortem",
      priority: "medium",
      due_date: "within_1_week"
    }
  ]

  Write(`.workflow/lite-fixes/${taskId}-followup.json`, follow_up_tasks)
}

Step 6.3: Real-time Monitoring (if selected)

if (user_selection.monitoring === "real-time") {
  console.log(`
  📊 Real-time Monitoring Active (15 minutes)

  Metrics:
  - Error rate: <5%
  - Login success: >95%
  - Auth latency: <500ms

  Auto-rollback: Enabled
  `)
}

TodoWrite: Mark Phase 6 completed

---

Data Structures

diagnosisContext

{
  symptom: string,
  error_message: string | null,
  keywords: string[],
  root_cause: {
    file: string,
    line_range: string,
    issue: string,
    introduced_by: string
  },
  reproduction_steps: string[],
  affected_scope: {...}
}

impactContext

{
  affected_users: { count: string, severity: string },
  system_risk: { availability: string, cascading_failures: string },
  business_impact: { revenue: string, reputation: string, sla_breach: string },
  risk_score: number,  // 0-10
  severity: "low" | "medium" | "high" | "critical"
}

fixPlan

{
  strategy: string,
  summary: string,
  approach: string,
  tasks: [{
    title: string,
    file: string,
    action: "Update" | "Create" | "Delete",
    implementation: string[],
    verification: string[]
  }],
  estimated_time: string,
  recommended_execution: "Agent" | "CLI" | "Manual"
}

executionContext (passed to lite-execute)

{
  mode: "bugfix",
  severity: "regular" | "critical" | "hotfix",
  planObject: fixPlan,
  diagnosisContext: diagnosisContext,
  impactContext: impactContext,
  verificationStrategy: {...},
  branchStrategy: {...},
  executionMethod: string,
  monitoringLevel: string
}

---

Best Practices

Severity Selection Guide

Use Regular Mode when:

• Bug is not blocking critical functionality
• Have time for comprehensive testing (2-4 hours)
• Want to explore multiple fix strategies
• Can afford full test suite run

Use Critical Mode when:

• Bug affects significant user base (>20%)
• Features degraded but not completely broken
• Need fix within 1 hour
• Have clear reproduction steps

Use Hotfix Mode when:

• Production is down or critically degraded
• Revenue/reputation at immediate risk
• SLA breach occurring
• Need fix within 30 minutes
• Issue is well-understood

Branching Best Practices

Hotfix Branching:

# ✅ Correct: Branch from production tag
git checkout -b hotfix/fix-name v2.3.1

# ❌ Wrong: Branch from main (unreleased code)
git checkout -b hotfix/fix-name main

Merge Strategy:

# Hotfix merges to both targets
git checkout main && git merge hotfix/fix-name
git checkout production && git merge hotfix/fix-name
git tag v2.3.2

Follow-up Task Management

Always create follow-up for hotfixes:

• ✅ Comprehensive fix (within 3 days)
• ✅ Test coverage improvement
• ✅ Monitoring/alerting enhancements
• ✅ Documentation updates
• ✅ Postmortem (if critical)

---

Error Handling

Error	Cause	Resolution
Root cause not found	Insufficient search	Expand search or escalate to /workflow:plan
Reproduction fails	Stale bug or env issue	Verify environment, request updated steps
Multiple causes	Complex interaction	Use /cli:discuss-plan for analysis
Fix too complex	High-risk refactor	Suggest /workflow:plan --mode refactor
Verification fails	Insufficient tests	Add test cases or adjust mode

---

Output Routing

Lite-fix directory:

.workflow/lite-fixes/
├── BUGFIX-2024-10-20T14-30-00.json          # Bug fix task JSON
├── BUGFIX-2024-10-20T14-30-00-followup.json # Follow-up tasks (hotfix)
└── diagnosis-cache/                          # Cached diagnosis
    └── auth-token-hash.json

Session-based (if active session):

.workflow/active/WFS-feature/
├── .bugfixes/
│   ├── BUGFIX-001.json
│   └── BUGFIX-001-followup.json
└── .summaries/
    └── BUGFIX-001-summary.md

---

Advanced Features

1. Diagnosis Caching

Speed up similar issues:

cache_key = hash(bug_keywords + recent_changes_hash)
cache_path = `.workflow/lite-fixes/diagnosis-cache/${cache_key}.json`

if (cache_exists && cache_age < 1_week) {
  diagnosis = load_from_cache()
}

2. Auto-Severity Detection

if (bug_description.includes("production|down|critical|outage")) {
  suggested_flag = "--critical"
} else if (bug_description.includes("hotfix|urgent|incident")) {
  suggested_flag = "--hotfix"
}

3. Rollback Plan (Hotfix)

rollback_plan = {
  method: "git_revert",
  commands: [
    "git revert ${commit_sha}",
    "git push origin hotfix/${branch}",
    "# Re-deploy v2.3.1"
  ],
  estimated_time: "5 minutes"
}

---

Related Commands

Diagnostic Commands:

• /cli:mode:bug-diagnosis - Root cause analysis only
• /cli:mode:code-analysis - Execution path tracing

Fix Execution:

• /workflow:lite-execute --in-memory - Execute fix plan (called by lite-fix)
• /cli:execute - Direct implementation
• /cli:codex-execute - Multi-stage fix

Planning Commands:

• /workflow:plan --mode bugfix - Complex bug requiring comprehensive planning
• /cli:discuss-plan - Multi-model collaborative analysis

Review Commands:

• /workflow:review --type quality - Post-fix code review
• /workflow:review --type security - Security validation

---

Comparison with Other Commands

Command	Use Case	Time	Output
/workflow:lite-fix	Bug fixes (regular to critical)	15min-4h	In-memory + JSON
/workflow:lite-plan	New features	1-6h	In-memory + JSON
/workflow:plan	Complex features	1-5 days	Persistent session
/cli:mode:bug-diagnosis	Analysis only	10-30min	Diagnostic report

---

Quality Gates

Before execution:

• Root cause identified (>80% confidence)
• Impact scope clearly defined
• Fix strategy reviewed and approved
• Verification plan matches risk level
• Branch strategy appropriate

Hotfix-specific:

• Incident ticket linked
• Incident commander approval
• Rollback plan documented
• Follow-up tasks generated
• Monitoring configured

---

When to Use lite-fix

✅ Good fit:

• Clear bug symptom with reproduction steps
• Localized fix (1-3 files)
• Time-sensitive but not catastrophic
• Known technology stack

❌ Poor fit:

• Root cause unclear → use /cli:mode:bug-diagnosis first
• Requires architectural changes → use /workflow:plan
• Complex legacy code → use /workflow:plan --legacy-refactor
• Performance investigation → use /workflow:plan --performance-optimization
• Data migration needed → use /workflow:plan --data-migration

---

Last Updated: 2025-11-20 Version: 1.0.0 Status: Design Document