Claude-Code-Workflow/LITE_FIX_DESIGN.md

Lite-Fix Command Design Document

Date: 2025-11-20 Version: 1.0.0 Status: Design Proposal Related: PLANNING_GAP_ANALYSIS.md (Scenario #8: 紧急修复场景)

---

设计概述

/workflow:lite-fix 是一个轻量级的bug诊断和修复工作流命令，填补了当前planning系统在紧急修复场景的空白。设计参考了 /workflow:lite-plan 的成功模式，针对bug修复场景进行优化。

核心设计理念

1. 快速响应 - 支持15分钟到4小时的修复周期
2. 风险感知 - 根据严重程度调整流程复杂度
3. 渐进式验证 - 从smoke test到全量测试的灵活策略
4. 自动化跟进 - Hotfix模式自动生成完善任务

---

设计对比：lite-fix vs lite-plan

维度	lite-plan	lite-fix	设计理由
目标场景	新功能开发	Bug修复	不同的开发意图
时间预算	1-6小时	15分钟-4小时	Bug修复更紧迫
探索阶段	可选（-e flag）	必需但可简化	Bug需要诊断
输出类型	实现计划	诊断+修复计划	Bug需要根因分析
验证策略	完整测试套件	分级验证（Smoke/Focused/Full）	风险vs速度权衡
分支策略	Feature分支	Feature/Hotfix分支	生产环境需要特殊处理
跟进机制	无	Hotfix自动生成跟进任务	技术债务管理

---

三种严重度模式设计

Mode 1: Regular (默认)

适用场景：

• 非阻塞性bug
• 影响<20%用户
• 有充足时间（2-4小时）

流程特点：

完整诊断 → 多策略评估 → 全量测试 → 标准分支

示例用例：

/workflow:lite-fix "用户头像上传失败，返回413错误"

Mode 2: Critical (--critical)

适用场景：

• 影响核心功能
• 影响20-50%用户
• 需要1小时内修复

流程简化：

聚焦诊断 → 单一最佳策略 → 关键场景测试 → 快速分支

示例用例：

/workflow:lite-fix --critical "购物车结算时随机丢失商品"

Mode 3: Hotfix (--hotfix)

适用场景：

• 生产完全故障
• 影响100%用户或业务中断
• 需要15-30分钟修复

流程最简：

最小诊断 → 外科手术式修复 → Smoke测试 → Hotfix分支 → 自动跟进任务

示例用例：

/workflow:lite-fix --hotfix --incident INC-2024-1015 "支付网关5xx错误"

---

六阶段执行流程设计

Phase 1: Diagnosis & Root Cause (诊断)

设计亮点：

• 智能搜索策略：Regular使用cli-explore-agent，Critical使用直接搜索，Hotfix使用已知信息
• 结构化输出：root_cause对象包含file、line_range、issue、introduced_by
• 可复现性验证：输出reproduction_steps供验证

技术实现：

if (mode === "regular") {
  // 使用cli-explore-agent深度探索
  Task(subagent_type="cli-explore-agent", ...)
} else if (mode === "critical") {
  // 直接使用grep + git blame
  Bash("grep -r '${error}' src/ | head -10")
} else {
  // 假设已知问题，跳过探索
  Read(suspected_file)
}

Phase 2: Impact Assessment (影响评估)

设计亮点：

• 量化风险评分：risk_score = user_impact×0.4 + system_risk×0.3 + business_impact×0.3
• 自动严重度建议：根据评分建议使用--critical或--hotfix
• 业务影响分析：包括revenue、reputation、SLA breach

输出示例：

## Impact Assessment
**Risk Level**: HIGH (7.1/10)
**Affected Users**: ~5000 (100%)
**Business Impact**: Revenue (Medium), Reputation (High), SLA Breached
**Recommended Severity**: --critical flag suggested

Phase 3: Fix Planning (修复规划)

设计亮点：

• 多策略生成（Regular）：immediate_patch vs comprehensive_refactor
• 单一最佳策略（Critical/Hotfix）：surgical_fix
• 复杂度自适应：低复杂度用Claude直接规划，中等复杂度用cli-lite-planning-agent

升级路径：

if (complexity > threshold) {
  suggest("/workflow:plan --mode bugfix")
}

Phase 4: Verification Strategy (验证策略)

三级验证设计：

Level	Test Scope	Duration	Pass Criteria
Smoke	核心路径	2-5分钟	无核心功能回归
Focused	受影响模块	5-10分钟	关键场景通过
Comprehensive	完整套件	10-20分钟	全部测试通过

分支策略差异：

if (mode === "hotfix") {
  branch = {
    type: "hotfix_branch",
    base: "production_tag_v2.3.1",  // ⚠️ 从生产tag创建
    merge_target: ["main", "production"]  // 双向合并
  }
}

Phase 5: User Confirmation (用户确认)

多维度确认设计：

Regular: 4维度

1. Fix strategy (Proceed/Modify/Escalate)
2. Execution method (Agent/CLI/Manual)
3. Verification level (Full/Focused/Smoke)
4. Code review (Gemini/Skip)

Critical: 3维度（跳过code review）

Hotfix: 2维度（最小确认）

1. Deploy confirmation (Deploy/Stage First/Abort)
2. Post-deployment monitoring (Real-time/Passive)

Phase 6: Execution & Follow-up (执行和跟进)

设计亮点：

• 统一执行接口：通过/workflow:lite-execute --in-memory --mode bugfix执行
• 自动跟进任务（Hotfix专属）：

  [
    {"id": "FOLLOWUP-comprehensive", "title": "完善修复", "due": "3天"},
    {"id": "FOLLOWUP-postmortem", "title": "事后分析", "due": "1周"}
  ]
  

• 实时监控（可选）：15分钟监控窗口，自动回滚触发器

---

与现有系统集成

1. 命令集成路径

graph TD
    A[Bug发现] --> B{严重程度?}
    B -->|不确定| C[/cli:mode:bug-diagnosis]
    C --> D[/workflow:lite-fix]

    B -->|一般| E[/workflow:lite-fix]
    B -->|紧急| F[/workflow:lite-fix --critical]
    B -->|生产故障| G[/workflow:lite-fix --hotfix]

    E --> H{复杂度?}
    F --> H
    G --> I[lite-execute]

    H -->|简单| I
    H -->|复杂| J[建议升级到 /workflow:plan]

    I --> K[修复完成]
    K --> L[/workflow:review --type quality]

2. 数据流设计

输入：

{
  bug_description: string,
  severity_flags: "--critical" | "--hotfix" | null,
  incident_id: string | null
}

内部数据结构：

• diagnosisContext: 根因分析结果
• impactContext: 影响评估结果
• fixPlan: 修复计划对象
• executionContext: 传递给lite-execute的上下文

输出：

{
  // In-memory (传递给lite-execute)
  executionContext: {...},

  // Optional: Persistent JSON
  `.workflow/lite-fixes/BUGFIX-${timestamp}.json`,

  // Hotfix专属：Follow-up tasks
  `.workflow/lite-fixes/BUGFIX-${timestamp}-followup.json`
}

3. 与lite-execute配合

lite-fix职责：

• ✅ 诊断和规划
• ✅ 影响评估
• ✅ 策略选择
• ✅ 用户确认

lite-execute职责：

• ✅ 代码实现
• ✅ 测试执行
• ✅ 分支操作
• ✅ 部署监控

交接机制：

// lite-fix准备executionContext
executionContext = {
  mode: "bugfix",
  severity: "hotfix",
  planObject: {...},
  diagnosisContext: {...},
  verificationStrategy: {...},
  branchStrategy: {...}
}

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

---

架构扩展点

1. Enhanced Task JSON Schema扩展

新增scenario类型：

{
  "scenario_type": "bugfix",
  "scenario_config": {
    "severity": "regular|critical|hotfix",
    "root_cause": {
      "file": "...",
      "line_range": "...",
      "issue": "..."
    },
    "impact_assessment": {
      "risk_score": 7.1,
      "affected_users_count": 5000
    }
  }
}

2. workflow-session.json扩展（如果使用session模式）

{
  "session_id": "WFS-bugfix-payment",
  "type": "bugfix",
  "severity": "critical",
  "incident_id": "INC-2024-1015",
  "bugfixes": [
    {
      "id": "BUGFIX-001",
      "status": "completed",
      "follow_up_tasks": ["FOLLOWUP-001", "FOLLOWUP-002"]
    }
  ]
}

3. 诊断缓存机制（高级特性）

设计目的：加速相似bug的诊断

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()
  console.log("Using cached diagnosis (similar issue found)")
}

---

质量保证机制

1. 质量门禁

执行前检查：

• 根因识别置信度>80%
• 影响范围明确定义
• 修复策略已审查批准
• 验证计划与风险匹配
• 分支策略符合严重度

Hotfix专属门禁：

• 事故工单已创建并关联
• 事故指挥官批准
• 回滚计划已文档化
• 跟进任务已生成
• 部署后监控已配置

2. 错误处理策略

错误	原因	解决方案
根因未找到	搜索范围不足	扩大搜索或升级到/workflow:plan
复现失败	过期bug或环境问题	验证环境，请求更新复现步骤
多个潜在原因	复杂交互	使用/cli:discuss-plan多模型分析
修复过于复杂	需要重构	建议/workflow:plan --mode refactor
Hotfix验证失败	Smoke测试不足	添加关键测试或降级到critical模式

---

实现优先级和路线图

Phase 1: 核心功能实现（Sprint 1）

必需功能：

• 命令文档完成（本文档）
• 六阶段流程实现
• 三种严重度模式支持
• 基础诊断逻辑
• 与lite-execute集成

预计工作量：5-8天

Phase 2: 高级特性（Sprint 2）

增强功能：

• 诊断缓存机制
• 自动严重度检测
• Hotfix分支管理
• 实时监控集成
• 跟进任务自动生成

预计工作量：3-5天

Phase 3: 优化和完善（Sprint 3）

优化项：

• 性能优化（诊断速度）
• 错误处理完善
• 文档和示例补充
• 用户反馈迭代

预计工作量：2-3天

---

成功度量指标

1. 使用指标

• 采用率：lite-fix使用次数 / 总bug修复次数
• 目标：>60%的常规bug使用lite-fix

2. 效率指标

• Regular模式：平均修复时间<3小时（vs 手动4-6小时）
• Critical模式：平均修复时间<1小时（vs 手动2-3小时）
• Hotfix模式：平均修复时间<30分钟（vs 手动1-2小时）

3. 质量指标

• 诊断准确率：根因识别准确率>85%
• 修复成功率：首次修复成功率>90%
• 回归率：引入新bug的比例<5%

4. 跟进完成率（Hotfix）

• 跟进任务完成率：>80%的跟进任务在deadline前完成
• 技术债务偿还：Hotfix的完善修复在3天内完成率>70%

---

风险和缓解措施

风险1: Hotfix误用导致生产问题

缓解措施：

1. 严格的质量门禁（需要事故指挥官批准）
2. 强制回滚计划文档化
3. 实时监控自动回滚触发器
4. 强制生成跟进任务

风险2: 诊断准确率不足

缓解措施：

1. 诊断置信度评分（<80%建议升级到/workflow:plan）
2. 提供多假设诊断（当不确定时）
3. 集成/cli:discuss-plan用于复杂case

风险3: 用户跳过必要验证

缓解措施：

1. 根据严重度强制最低验证级别
2. 显示风险警告（跳过测试的后果）
3. Hotfix模式禁止跳过smoke测试

---

与PLANNING_GAP_ANALYSIS的对应关系

本设计是对 PLANNING_GAP_ANALYSIS.md 中 场景8: 紧急修复场景 的完整实现方案。

Gap覆盖情况：

Gap项	覆盖程度	实现方式
流程简化	✅ 100%	三种严重度模式
快速验证	✅ 100%	分级验证策略
Hotfix分支管理	✅ 100%	branchStrategy配置
事后补充完整修复	✅ 100%	自动跟进任务生成

额外增强：

• ✅ 诊断缓存机制（未在原gap中提及）
• ✅ 实时监控集成（超出原需求）
• ✅ 自动严重度建议（智能化增强）

---

设计决策记录

ADR-001: 为什么不复用/workflow:plan?

决策：创建独立的lite-fix命令

理由：

1. Bug修复的核心是"诊断"，而plan的核心是"设计"
2. Bug修复需要风险分级（Regular/Critical/Hotfix），plan不需要
3. Bug修复需要Hotfix分支管理，plan使用标准feature分支
4. Bug修复需要跟进任务机制，plan假设一次性完成

替代方案被拒绝：/workflow:plan --mode bugfix

• 问题：plan流程太重，不适合15分钟hotfix场景

ADR-002: 为什么分三种严重度而不是连续评分?

决策：使用离散的Regular/Critical/Hotfix模式

理由：

1. 清晰的决策点（用户容易选择）
2. 每个模式有明确的流程差异
3. 避免"评分8.5应该用什么流程"的模糊性

替代方案被拒绝：0-10连续评分自动选择流程

• 问题：评分边界模糊，用户难以理解为什么某个分数用某个流程

ADR-003: 为什么诊断是必需而非可选?

决策：Phase 1诊断在所有模式下都是必需的（但复杂度可调整）

理由：

1. 即使是已知bug，也需要验证复现路径
2. 诊断输出对后续修复质量至关重要
3. 跳过诊断容易导致修错问题（修了A却没修B）

替代方案被拒绝：Hotfix模式完全跳过诊断

• 问题：增加误修风险，事后难以生成postmortem

---

总结

/workflow:lite-fix 是对当前planning系统的重要补充，专注于bug修复这一特定场景。设计充分借鉴了lite-plan的成功经验，同时针对bug修复的特殊需求进行了优化：

核心优势：

1. ⚡ 快速响应：15分钟到4小时的修复周期
2. 🎯 风险感知：三种严重度模式适配不同紧急程度
3. 🔍 智能诊断：结构化根因分析
4. 🛡️ 质量保证：分级验证+强制门禁
5. 📋 技术债务管理：Hotfix自动生成完善任务

与现有系统协同：

• 与 /workflow:lite-plan 形成"修复-开发"双子命令
• 复用 /workflow:lite-execute 执行层
• 集成 /cli:mode:bug-diagnosis 诊断能力
• 支持升级到 /workflow:plan 处理复杂场景

预期影响：

• 减少bug修复时间50-70%
• 提升诊断准确率到85%+
• 减少生产hotfix风险
• 系统化管理技术债务

---

文档版本: 1.0.0 作者: Claude (Sonnet 4.5) 审阅状态: 待审阅 实现状态: 设计阶段（待开发）