focused-fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Focused Fix — Deep-Dive Feature Repair

聚焦修复——深度功能修复

When to Use

适用场景

Activate when the user asks to fix, debug, or make a specific feature/module/area work. Key triggers:

"make X work"
"fix the Y feature"
"the Z module is broken"
"focus on [area]"
"this feature needs to work properly"

This is NOT for quick single-bug fixes (use systematic-debugging for that). This is for when an entire feature or module needs systematic repair — tracing every dependency, reading logs, checking tests, mapping the full dependency graph.

dot

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"];
}

当用户要求修复、调试或让特定功能/模块/区域正常工作时启用。关键触发词：

"让X正常工作"
"修复Y功能"
"Z模块坏了"
"专注于[某个区域]"
"这个功能需要正常运行"

注意：此方法不适用于快速修复单个bug（此类场景请使用systematic-debugging）。它适用于整个功能或模块需要系统性修复的场景——追踪所有依赖、读取日志、检查测试、绘制完整依赖图谱。

dot

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"];
}

The Iron Law

铁则

NO FIXES WITHOUT COMPLETING SCOPE → TRACE → DIAGNOSE FIRST

If you haven't finished Phase 3, you cannot propose fixes. Period.

Violating the letter of these phases is violating the spirit of focused repair.

未完成范围界定→追踪→诊断前，禁止进行任何修复

如果尚未完成第3阶段，不得提出修复方案，这是硬性规定。

违反阶段顺序即违反深度修复的核心原则。

Protocol — STRICTLY follow these 5 phases IN ORDER

流程——严格按顺序遵循以下5个阶段

dot

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"];
}

dot

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"];
}

Phase 1: SCOPE — Map the Feature Boundary

阶段1：范围界定——绘制功能边界

Before touching any code, understand the full scope of the feature.

Ask the user: "Which feature/folder should I focus on?" if not already clear
Identify the PRIMARY folder/files for this feature
Map EVERY file in that folder — read each one, understand its purpose
Create a feature manifest:

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

在接触任何代码之前，先明确功能的完整范围。

如果用户未明确说明，询问：“我应该聚焦哪个功能/文件夹？”
确定该功能的主文件夹/文件
梳理该文件夹下的所有文件——逐一阅读，理解其用途
创建功能清单：

功能范围:
  主路径: src/features/auth/
  入口文件: [被应用其他部分引入的文件]
  内部文件: [仅在该功能内使用的文件]
  文件总数: N
  代码总行数: N

Phase 2: TRACE — Map All Dependencies (Inside AND Outside)

阶段2：追踪——绘制所有依赖（内部和外部）

Trace every connection this feature has to the rest of the codebase.

INBOUND (what this feature imports):

For every import statement in every file in the feature folder:
- Trace it to its source
- Verify the source file exists
- Verify the imported entity (function, type, component) exists and is exported
- Check if the types/signatures match what the feature expects
Check for:
- Environment variables used (grep for process.env, import.meta.env, os.environ, etc.)
- Config files referenced
- Database models/schemas used
- API endpoints called
- Third-party packages imported

OUTBOUND (what imports this feature):

Search the entire codebase for imports from this feature folder
For each consumer:
- Verify they're importing entities that actually exist
- Check if they're using the correct API/interface
- Note if any consumers are using deprecated patterns

Output format:

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)

追踪该功能与代码库其他部分的所有关联。

入站依赖（该功能引入的内容）：

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

出站依赖（引入该功能的内容）：

在整个代码库中搜索从该功能文件夹导入的内容
针对每个调用方：
- 验证他们导入的实体确实存在
- 检查他们是否使用了正确的API/接口
- 记录是否有调用方使用了已废弃的模式

输出格式：

依赖图谱:
  入站依赖（该功能依赖的内容）:
    src/lib/db.ts → 在auth/repository.ts中使用（getUserById, createUser）
    src/lib/jwt.ts → 在auth/service.ts中使用（signToken, verifyToken）
    @prisma/client → 在auth/repository.ts中使用
    process.env.JWT_SECRET → 在auth/service.ts中使用
    process.env.DATABASE_URL → 通过prisma使用

  出站依赖（依赖该功能的内容）:
    src/app/api/login/route.ts → 从auth/service导入{ login }
    src/app/api/register/route.ts → 从auth/service导入{ register }
    src/middleware.ts → 从auth/service导入{ verifyToken }

  必填环境变量: JWT_SECRET, DATABASE_URL
  配置文件: prisma/schema.prisma（User模型）

Phase 3: DIAGNOSE — Find Every Issue

阶段3：诊断——排查所有问题

Systematically check for problems. Run ALL of these checks:

CODE QUALITY:

Every import resolves to a real file/export
No circular dependencies within the feature
Types are consistent across boundaries (no
```
any
```
at interfaces)
Error handling exists for all async operations
No TODO/FIXME/HACK comments indicating known issues

RUNTIME:

All required environment variables are set (check .env)
Database migrations are up to date (if applicable)
API endpoints return expected shapes
No hardcoded values that should be configurable

TESTS:

Run ALL tests related to this feature: find them by searching for imports from the feature folder
Record every failure with full error output
Check test coverage — are there untested code paths?

LOGS & ERRORS:

Search for any log files, error reports, or Sentry-style error tracking
Check git log for recent changes to this feature:
```
git log --oneline -20 -- <feature-path>
```

Check if any recent commits might have broken something:

git log --oneline -5 --all -- <files that this feature depends on>

CONFIGURATION:

Verify all config files this feature depends on are valid
Check for mismatches between development and production configs
Verify third-party service credentials are valid (if testable)

ROOT-CAUSE CONFIRMATION: For each CRITICAL issue found, confirm root cause before adding it to the fix list:

State clearly: "I think X is the root cause because Y"
Trace the data/control flow backward to verify — don't trust surface-level symptoms
If the issue spans multiple components, add diagnostic logging at each boundary to identify which layer fails
REQUIRED SUB-SKILL: For complex bugs found during diagnosis, apply
```
superpowers:systematic-debugging
```
Phase 1 (Root Cause Investigation) to confirm before proceeding

RISK LABELING: Assign each issue a risk label:

Risk	Criteria
HIGH	Public API surface / breaking interface contract / DB schema / auth or security logic / widely imported module (>3 callers) / git hotspot
MED	Internal module with tests / shared utility / config with runtime impact / internal callers of changed functions
LOW	Leaf module / isolated file / test-only change / single-purpose helper with no callers

Output format:

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]

系统性检查问题，执行以下所有检查：

代码质量:

所有导入都指向真实文件/导出项
功能内部无循环依赖
边界处类型一致（接口无
```
any
```
类型）
所有异步操作都有错误处理
无TODO/FIXME/HACK等标注已知问题的注释

运行时:

所有必填环境变量已设置（检查.env文件）
数据库迁移已更新（如适用）
API端点返回预期格式
无应配置化却硬编码的值

测试:

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

日志与错误:

搜索所有日志文件、错误报告或类似Sentry的错误追踪记录
检查该功能的近期git提交记录：
```
git log --oneline -20 -- <feature-path>
```

检查是否有近期提交可能导致问题：

git log --oneline -5 --all -- <该功能依赖的文件>

配置:

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

根因确认: 对于每个发现的关键问题，在加入修复列表前确认根因：

明确说明：“我认为X是根因，因为Y”
反向追踪数据/控制流以验证——不要轻信表面症状
如果问题跨多个组件，在每个边界添加诊断日志以确定哪一层失败
必备子技能: 诊断过程中发现复杂bug时，应用
```
superpowers:systematic-debugging
```
的第1阶段（根因调查）确认后再继续

风险标记: 为每个问题分配风险标签：

风险等级	判断标准
高	公开API接口/破坏接口契约/数据库schema/认证或安全逻辑/被广泛导入的模块（>3个调用方）/git热点文件
中	带测试的内部模块/共享工具类/对运行时有影响的配置/修改后函数的内部调用方
低	叶子模块/孤立文件/仅测试相关的修改/无调用方的单一用途辅助函数

输出格式：

诊断报告:
  发现问题数: N

  关键问题:
    1. [高] [文件:行号] — 问题描述。根因: [已确认的解释]
    2. [高] [文件:行号] — 问题描述。根因: [已确认的解释]

  警告问题:
    1. [中] [文件:行号] — 问题描述
    2. [低] [文件:行号] — 问题描述

  测试情况:
    运行测试数: N
    通过数: N
    失败数: N
    [逐一列出每个失败案例的一行摘要]

Phase 4: FIX — Repair Everything Systematically

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

Fix issues in this EXACT order:

DEPENDENCIES FIRST — fix broken imports, missing packages, wrong versions
TYPES SECOND — fix type mismatches at feature boundaries
LOGIC THIRD — fix actual business logic bugs
TESTS FOURTH — fix or create tests for each fix
INTEGRATION LAST — verify the feature works end-to-end with its consumers

Rules:

Fix ONE issue at a time
After each fix, run the related test to confirm it works
If a fix breaks something else, STOP and re-evaluate (go back to DIAGNOSE)
Keep a running log of every change made
Never change code outside the feature folder without explicitly stating why
Fix HIGH-risk issues before MED, MED before LOW

ESCALATION RULE — 3-Strike Architecture Check: If 3+ fixes in this phase create NEW issues (not pre-existing ones), STOP immediately.

This pattern indicates an architectural problem, not a bug collection:

Each fix reveals new shared state / coupling / problem in a different place
Fixes require "massive refactoring" to implement
Each fix creates new symptoms elsewhere

Action: Stop fixing. Tell the user: "3+ fixes have cascaded into new issues. This suggests the feature's architecture may need rethinking, not patching. Here's what I've found: [summary]. Should we continue fixing symptoms or discuss restructuring?"

Do NOT attempt fix #4 without this discussion.

Output after each fix:

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

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

优先修复依赖 — 修复损坏的导入、缺失的包、错误的版本
其次修复类型 — 修复功能边界处的类型不匹配
然后修复逻辑 — 修复实际业务逻辑bug
接着修复测试 — 为每个修复项修复或创建测试
最后修复集成 — 验证功能与其调用方端到端正常工作

规则:

一次修复一个问题
每次修复后，运行相关测试确认生效
如果某个修复破坏了其他内容，立即停止并重新评估（返回诊断阶段）
记录所有修改内容
未经明确说明，不得修改功能文件夹外的代码
先修复高风险问题，再修复中风险，最后修复低风险

升级规则——三次架构检查触发条件: 如果此阶段中3次及以上修复引发了新问题（非原有问题），立即停止。

这种模式表明存在架构问题，而非单纯的bug集合：

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

行动: 停止修复。告知用户：“3次及以上修复引发了连锁问题。这表明该功能的架构可能需要重新设计，而非打补丁。以下是我的发现：[摘要]。我们应该继续修复症状还是讨论重构方案？”

未进行此讨论前，不得尝试第4次修复。

每次修复后的输出格式：

修复项 #1:
  文件: auth/service.ts:45
  问题: signToken调用时参数顺序错误
  修改: 将(expiresIn, payload)改为(payload, expiresIn)
  测试: auth.test.ts → 通过

Phase 5: VERIFY — Confirm Everything Works

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

After all fixes are applied:

Run ALL tests in the feature folder — every single one must pass
Run ALL tests in files that IMPORT from this feature — must pass
Run the full test suite if available — check for regressions
If the feature has a UI, describe how to manually verify it
Summarize all changes made

Final output:

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 ✅

所有修复完成后：

运行功能文件夹下的所有测试——必须全部通过
运行所有导入该功能的文件的测试——必须全部通过
如果有完整测试套件，运行全套测试——检查是否有回归问题
如果功能有UI，描述手动验证的方法
总结所有修改内容

最终输出格式：

聚焦修复完成:
  功能: auth
  修改文件数: 4
  总修复项数: 7
  测试情况: 23/23 通过
  回归问题: 0

  修改内容:
    1. auth/service.ts — 修复令牌签名参数顺序
    2. auth/repository.ts — 添加用户查询的空值检查
    3. auth/middleware.ts — 修复异步错误处理
    4. auth/types.ts — 对齐UserResponse类型与实际数据库schema

  已验证的调用方:
    - src/app/api/login/route.ts ✅
    - src/app/api/register/route.ts ✅
    - src/middleware.ts ✅

Red Flags — STOP and Return to Current Phase

警示信号——立即停止并返回当前阶段

If you catch yourself thinking any of these, you are skipping phases:

"I can see the bug, let me just fix it" → STOP. You haven't traced dependencies yet.
"Scoping is overkill, it's obviously just this file" → STOP. That's always wrong for feature-level fixes.
"I'll map dependencies after I fix the obvious stuff" → STOP. You'll miss root causes.
"The user said fix X, so I only need to look at X" → STOP. Features have dependencies.
"Tests are passing so I'm done" → STOP. Did you run consumer tests too?
"I don't need to check env vars for this" → STOP. Config issues masquerade as code bugs.
"One more fix should do it" (after 2+ cascading failures) → STOP. Escalate.
"I'll skip the diagnosis report, the fixes are obvious" → STOP. Write it down.

ALL of these mean: Return to the phase you're supposed to be in.

如果你出现以下想法，说明你正在跳过阶段：

“我能看到bug，直接修复就行” → 停止。你还未追踪依赖。
“范围界定没必要，显然只是这个文件的问题” → 停止。对于功能级修复，这种想法永远是错的。
“我先修复明显的问题，之后再梳理依赖” → 停止。你会遗漏根因。
“用户说修复X，所以我只需要看X” → 停止。功能都有依赖。
“测试通过了，我完成了” → 停止。你有没有运行调用方的测试？
“这个功能不需要检查环境变量” → 停止。配置问题常伪装成代码bug。
“再修复一次应该就好了”（已经出现2次及以上连锁失败）→ 停止。升级处理。
“修复方案很明显，我不需要写诊断报告” → 停止。请记录下来。

以上所有情况均意味着：回到你当前应处于的阶段。

Common Rationalizations

常见借口与真相

Excuse	Reality
"The feature is small, I don't need all 5 phases"	Small features have dependencies too. Phases 1-2 take minutes for small features — do them.
"I already know this codebase"	Knowledge decays. Trace the actual imports, don't rely on memory.
"The user wants speed, not process"	Skipping phases causes rework. Systematic is faster than thrashing.
"Only one file is broken"	If only one file were broken, the user would say "fix this bug", not "make the feature work."
"I fixed the tests, so it works"	Tests can pass while consumers are broken. Verify Phase 5 fully.
"The dependency map is too big to trace"	Then the feature is too big to fix without tracing. That's exactly why you need it.
"Root cause is obvious, I don't need to confirm"	"Obvious" root causes are wrong 40% of the time. Confirm with evidence.
"3 cascading failures is normal for a big fix"	3 cascading failures means you're patching symptoms of an architectural problem.

借口	真相
“这个功能很小，我不需要走完5个阶段”	小功能也有依赖。阶段1-2对于小功能只需几分钟——请执行。
“我已经熟悉这个代码库了”	知识会遗忘。追踪实际的导入，不要依赖记忆。
“用户想要速度，不想走流程”	跳过阶段会导致返工。系统性修复比盲目尝试更快。
“只有一个文件坏了”	如果真的只有一个文件坏了，用户会说“修复这个bug”，而非“让这个功能正常工作”。
“我修复了测试，所以功能正常了”	测试通过不代表调用方正常。请完整执行阶段5的验证。
“依赖图谱太大，没法追踪”	这说明该功能太大，必须通过追踪才能修复。这正是你需要依赖图谱的原因。
“根因很明显，我不需要确认”	“明显”的根因有40%的概率是错的。请用证据确认。
“大型修复出现3次连锁失败很正常”	3次连锁失败说明你在修复架构问题的症状，而非根源。

Anti-Patterns — NEVER do these

反模式——绝对不要做这些

Anti-Pattern	Why It's Wrong
Starting to fix code before mapping all dependencies	You'll miss root causes and create whack-a-mole fixes
Fixing only the file the user mentioned	Related files likely have issues too
Ignoring environment variables and configuration	Many "code bugs" are actually config issues
Skipping the test run phase	You can't verify fixes without running tests
Making changes outside the feature folder without explaining why	Unexpected side effects confuse the user
Fixing symptoms in consumer files instead of root cause in feature	Band-aids that break when the next consumer appears
Declaring "done" without running verification tests	Untested fixes are unverified fixes
Changing the public API without updating all consumers	Breaks everything that depends on the feature

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

Related Skills

Quick Reference

快速参考

Phase	Key Action	Output
SCOPE	Read every file, map entry points	Feature manifest
TRACE	Map inbound + outbound dependencies	Dependency map
DIAGNOSE	Check code, runtime, tests, logs, config	Diagnosis report
FIX	Fix in order: deps → types → logic → tests → integration	Fix log per issue
VERIFY	Run all tests, check consumers, summarize	Completion report

阶段	核心动作	输出
范围界定	阅读所有文件，绘制入口点	功能清单
追踪	绘制入站+出站依赖	依赖图谱
诊断	检查代码、运行时、测试、日志、配置	诊断报告
修复	按顺序修复：依赖→类型→逻辑→测试→集成	每个问题的修复日志
验证	运行所有测试，检查调用方，总结	完成报告