focused-fix

聚焦修复 — 深度功能修复

适用场景

当用户要求修复、调试或让某个特定功能/模块/区域正常工作时启用。主要触发语句：

• "让 X 正常工作"
• "修复 Y 功能"
• "Z 模块坏了"
• "聚焦 [区域]"
• "这个功能需要正常工作"

这不适用于快速修复单个缺陷（此类情况请使用 systematic-debugging）。本技能适用于需要对整个功能或模块进行系统性修复的情况，包括追踪每一项依赖、阅读日志、检查测试、梳理完整的依赖图。

digraph when_to_use {
    "User reports feature broken" [shape=diamond];
    "Single bug or symptom?" [shape=diamond];
    "Use systematic-debugging" [shape=box];
    "Entire feature/module needs repair?" [shape=diamond];
    "Use focused-fix" [shape=box];
    "Something else" [shape=box];

    "User reports feature broken" -> "Single bug or symptom?";
    "Single bug or symptom?" -> "Use systematic-debugging" [label="yes"];
    "Single bug or symptom?" -> "Entire feature/module needs repair?" [label="no"];
    "Entire feature/module needs repair?" -> "Use focused-fix" [label="yes"];
    "Entire feature/module needs repair?" -> "Something else" [label="no"];
}

铁律

NO FIXES WITHOUT COMPLETING SCOPE → TRACE → DIAGNOSE FIRST

如果尚未完成阶段 3，则不能提出修复方案。没有例外。

违反这些阶段的字面要求，就是违反聚焦修复的精神。

流程 — 必须严格按顺序执行这 5 个阶段

digraph phases {
    rankdir=LR;
    SCOPE [shape=box, label="Phase 1\nSCOPE"];
    TRACE [shape=box, label="Phase 2\nTRACE"];
    DIAGNOSE [shape=box, label="Phase 3\nDIAGNOSE"];
    FIX [shape=box, label="Phase 4\nFIX"];
    VERIFY [shape=box, label="Phase 5\nVERIFY"];

    SCOPE -> TRACE -> DIAGNOSE -> FIX -> VERIFY;
    FIX -> DIAGNOSE [label="fix broke\nsomething else"];
    FIX -> ESCALATE [label="3+ fixes\ncreate new issues"];
    ESCALATE [shape=doubleoctagon, label="STOP\nQuestion Architecture\nDiscuss with User"];
}

阶段 1：范围 — 梳理功能边界

在修改任何代码之前，先全面了解该功能的范围。

1. 如果尚不明确，询问用户："我应该聚焦哪个功能/文件夹？"
2. 确定该功能的主要文件夹/文件
3. 梳理该文件夹中的每一个文件——逐个阅读，理解其用途
4. 创建功能清单：

FEATURE SCOPE:
  Primary path: src/features/auth/
  Entry points: [files that are imported by other parts of the app]
  Internal files: [files only used within this feature]
  Total files: N
  Total lines: N

阶段 2：追踪 — 梳理所有依赖（内部与外部）

追踪该功能与代码库其余部分之间的每一项连接。

入站（该功能导入的内容）：

1. 对功能文件夹中每个文件的每条 import 语句：
   • 追踪其来源
   • 验证来源文件存在
   • 验证被导入的实体（函数、类型、组件）存在且已导出
   • 检查类型/签名是否与该功能的预期一致
2. 检查以下内容：
   • 使用的环境变量（搜索 process.env、import.meta.env、os.environ 等）
   • 引用的配置文件
   • 使用的数据库模型/模式
   • 调用的 API 端点
   • 导入的第三方包

出站（导入该功能的内容）：

1. 在整个代码库中搜索从该功能文件夹导入的内容
2. 对每个使用方：
   • 验证其导入的实体确实存在
   • 检查其是否使用了正确的 API/接口
   • 记录是否有使用方在使用已弃用的写法

输出格式：

DEPENDENCY MAP:
  Inbound (this feature depends on):
    src/lib/db.ts → used in auth/repository.ts (getUserById, createUser)
    src/lib/jwt.ts → used in auth/service.ts (signToken, verifyToken)
    @prisma/client → used in auth/repository.ts
    process.env.JWT_SECRET → used in auth/service.ts
    process.env.DATABASE_URL → used via prisma

  Outbound (depends on this feature):
    src/app/api/login/route.ts → imports { login } from auth/service
    src/app/api/register/route.ts → imports { register } from auth/service
    src/middleware.ts → imports { verifyToken } from auth/service

  Env vars required: JWT_SECRET, DATABASE_URL
  Config files: prisma/schema.prisma (User model)

阶段 3：诊断 — 找出所有问题

系统地检查问题。运行以下所有检查：

代码质量：

• 每个导入都能解析到真实文件或导出项
• 功能内部没有循环依赖
• 各边界间的类型保持一致（接口中不使用 any）
• 所有异步操作都有错误处理
• 没有表示已知问题的 TODO/FIXME/HACK 注释

运行时：

• 已设置所有必需的环境变量（检查 .env）
• 数据库迁移均为最新状态（如适用）
• API 端点返回预期的数据结构
• 没有本应可配置的硬编码值

测试：

• 运行与此功能相关的所有测试：搜索从该功能文件夹导入的内容来查找测试
• 记录每项测试失败的完整错误输出
• 检查测试覆盖率——是否存在未测试的代码路径？

日志和错误：

• 搜索所有日志文件、错误报告或 Sentry 风格的错误跟踪
• 检查该功能的近期 git 记录：git log --oneline -20 -- <feature-path>
• 检查近期提交是否可能导致问题：git log --oneline -5 --all -- <files that this feature depends on>

配置：

• 验证此功能依赖的所有配置文件是否有效
• 检查开发环境与生产环境的配置是否存在不一致
• 验证第三方服务凭据是否有效（如果可以测试）

根因确认： 对于发现的每个严重问题，在将其加入修复列表前确认根因：

• 清楚地说明：“我认为 X 是根因，因为 Y”
• 反向追踪数据流或控制流以进行验证——不要轻信表面症状
• 如果问题涉及多个组件，在每个边界添加诊断日志，以确定故障所在层
• 对于复杂的 Bug，先进行根因调查再继续：稳定地复现故障，阅读完整错误信息和堆栈跟踪，检查近期变更（git log、git diff），并一次提出一个假设，通过尽可能小的改动进行测试。假设通过测试前，不要将 Bug 加入修复列表。

风险标记： 为每个问题指定风险标签：

风险	标准
HIGH	公共 API 表面 / 破坏接口契约 / 数据库架构 / 身份验证或安全逻辑 / 被广泛导入的模块（>3 个调用方）/ git 热点
MED	有测试的内部模块 / 共享工具 / 对运行时有影响的配置 / 对已更改函数的内部调用方
LOW	叶子模块 / 独立文件 / 仅测试改动 / 没有调用方的单一用途辅助函数

输出格式：

DIAGNOSIS REPORT:
  Issues found: N

  CRITICAL:
    1. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]
    2. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]

  WARNINGS:
    1. [MED] [file:line] — description of issue
    2. [LOW] [file:line] — description of issue

  TESTS:
    Ran: N tests
    Passed: N
    Failed: N
    [list each failure with one-line summary]

阶段 4：修复 — 系统性地修复所有问题

严格按以下顺序修复问题：

1. 先修复依赖 — 修复导入错误、缺失的包和错误的版本
2. 再修复类型 — 修复功能边界处的类型不匹配
3. 然后修复逻辑 — 修复实际的业务逻辑错误
4. 接着修复测试 — 为每项修复修复或创建测试
5. 最后进行集成验证 — 验证该功能与其使用方端到端正常工作

规则：

• 一次只修复一个问题
• 每次修复后，运行相关测试以确认修复有效
• 如果某项修复导致其他问题，立即停止并重新评估（返回诊断阶段）
• 持续记录所做的每项更改
• 除非明确说明原因，否则不要更改功能文件夹之外的代码
• 先修复高风险问题，再修复中风险问题，最后修复低风险问题

升级规则 — 三次触发架构检查： 如果此阶段有 3 项或更多修复引发了新问题（而非原先就存在的问题），请立即停止。

这种模式表明存在架构问题，而不是一堆互不相关的错误：

• 每次修复都会在不同位置暴露新的共享状态、耦合或问题
• 修复需要进行“大规模重构”才能实现
• 每次修复都会在其他地方引发新的症状

操作： 停止修复。告诉用户：“有 3 项或更多修复引发了新问题。这表明该功能的架构可能需要重新思考，而不是继续打补丁。以下是我发现的问题：[摘要]。我们应该继续修复这些症状，还是讨论重构？”

在进行此讨论前，不要尝试第 4 项修复。

每次修复后的输出：

FIX #1:
  File: auth/service.ts:45
  Issue: signToken called with wrong argument order
  Change: swapped (expiresIn, payload) to (payload, expiresIn)
  Test: auth.test.ts → PASSES

阶段 5：验证 — 确认所有内容均正常工作

完成所有修复后：

1. 运行功能文件夹中的所有测试 — 必须全部通过
2. 运行所有导入此功能的文件中的测试 — 必须通过
3. 如果可以，运行完整测试套件 — 检查是否出现回归问题
4. 如果该功能包含 UI，请说明如何手动验证
5. 总结所做的所有更改

最终输出：

FOCUSED FIX COMPLETE:
  Feature: auth
  Files changed: 4
  Total fixes: 7
  Tests: 23/23 passing
  Regressions: 0

  Changes:
    1. auth/service.ts — fixed token signing argument order
    2. auth/repository.ts — added null check for user lookup
    3. auth/middleware.ts — fixed async error handling
    4. auth/types.ts — aligned UserResponse type with actual DB schema

  Consumers verified:
    - src/app/api/login/route.ts ✅
    - src/app/api/register/route.ts ✅
    - src/middleware.ts ✅

危险信号 — 停止并返回当前阶段

如果你发现自己产生了以下任何想法，说明你正在跳过阶段：

• “我看出问题了，我直接修复吧” → 停止。你还没有追踪依赖关系。
• “范围界定没必要，这显然只涉及这个文件” → 停止。对于功能级修复，这种想法总是错的。
• “我修完明显的问题后再梳理依赖关系” → 停止。你会漏掉根本原因。
• “用户说要修复 X，所以我只需查看 X” → 停止。功能有依赖项。
• “测试都通过了，我可以结束了” → 停止。你也运行了使用方测试吗？
• “这个问题不用检查环境变量” → 停止。配置问题常会伪装成代码错误。
• “再修一次应该就行了”（在出现 2 次或更多级联故障后） → 停止。升级处理。
• “我可以跳过诊断报告，修复方法很明显” → 停止。把结论写下来。

以上任何一种情况都意味着：返回你当前应该处于的阶段。

常见的自我辩解

借口	实际情况
“功能很小，不需要完整走完 5 个阶段”	小功能也有依赖项。小功能的阶段 1–2 只需几分钟，照样要做。
“我已经熟悉这个代码库了”	知识会过时。追踪实际导入关系，不要依赖记忆。
“用户想要的是速度，不是流程”	跳过阶段只会导致返工。系统化处理比反复折腾更快。
“只有一个文件坏了”	如果真的只有一个文件坏了，用户会说“修复这个错误”，而不是“让这个功能正常工作”。
“我修复了测试，所以功能能用了”	即使测试通过，使用方也可能出问题。请完整执行阶段 5 的验证。
“依赖关系图太大，无法追踪”	那么在不追踪依赖关系的情况下就无法修复这个功能。这正是需要梳理依赖关系的原因。
“根本原因显而易见，不需要确认”	“显而易见”的根本原因有 40% 都是错的。请用证据确认。
“大型修复中出现 3 次级联故障很正常”	3 次级联故障意味着你在修补架构问题引发的症状。

反模式 — 绝对不要这样做

反模式	错误原因
尚未梳理所有依赖关系就开始修复代码	你会遗漏根本原因，并陷入打地鼠式修复
只修复用户提到的文件	相关文件可能也有问题
忽略环境变量和配置	很多“代码错误”实际上是配置问题
跳过测试阶段	不运行测试就无法验证修复
不说明原因就更改功能文件夹以外的内容	意料之外的副作用会让用户困惑
在调用方文件中修复症状，而不是修复功能中的根本原因	这种权宜之计会在出现下一个调用方时失效
未运行验证测试就宣布“完成”	未测试的修复就是未经验证的修复
更改公共 API，却不更新所有调用方	会破坏所有依赖此功能的内容

相关技能

• self-eval（本仓库，engineering/skills/self-eval）——第 5 阶段后使用，在报告完成前如实评估修复
• incident-commander（本仓库，engineering-team/skills/incident-commander，独立插件）——如果故障功能是线上生产事故，而不是本地修复，请改用此技能
• **可选，若已安装：**第三方 superpowers 插件中的 systematic-debugging 和 verification-before-completion 技能，涵盖的内容与第 3 阶段的根因排查步骤和第 5 阶段的检查相同。本技能不依赖它们；上述步骤本身已完整。

快速参考

阶段	关键操作	输出
SCOPE	阅读每个文件，梳理入口点	功能清单
TRACE	梳理入站和出站依赖关系	依赖关系图
DIAGNOSE	检查代码、运行时、测试、日志和配置	诊断报告
FIX	按顺序修复：依赖 → 类型 → 逻辑 → 测试 → 集成	每个问题的修复日志
VERIFY	运行所有测试，检查调用方并总结	完成报告