Back to Details

focused-fix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Focused Fix

Focused Fix

Category: Engineering Domain: Debugging & Maintenance
分类: 工程 领域: 调试与维护

Overview

概述

The Focused Fix skill enforces a disciplined minimal-change approach to bug fixing. Instead of refactoring or improving code during a bugfix, it identifies the smallest possible change set that resolves the issue. This reduces risk, simplifies code review, and prevents scope creep.
Focused Fix Skill 采用严谨的最小改动方法进行bug修复。它不会在修复bug时重构或优化代码，而是找出能够解决问题的最小改动集合。这种方法可以降低风险、简化代码评审，并防止范围蔓延。

Use when

使用场景

  • The user asks to "fix a bug with minimal changes", "do a focused bugfix", or "scope a minimal repair"
  • A bug report needs triage to identify the smallest set of files to touch
  • A PR is at risk of scope creep (unrelated refactors, style changes, "nearby" fixes)
  • A hotfix or release-blocker needs a low-risk, reviewable change set
  • The user asks "what is the minimal change to fix X?" or "which files do I need to touch for this bug?"
  • 用户要求“以最小改动修复bug”“进行针对性bug修复”或“确定最小修复范围”
  • 需要对bug报告进行分类，找出需要修改的最小文件集
  • 拉取请求（PR）存在范围蔓延风险（无关的重构、样式更改、“顺带”修复）
  • 紧急修复（hotfix）或发布阻塞问题需要低风险、易评审的改动集合
  • 用户询问“修复X的最小改动是什么？”或“修复这个bug需要修改哪些文件？”

Quick Start

快速开始

bash
undefined
bash
undefined

Analyze a bug description to identify minimal change scope

分析bug描述以确定最小改动范围

python scripts/change_scope_analyzer.py --bug "Login fails when email has + character" --path ./src
python scripts/change_scope_analyzer.py --bug "Login fails when email has + character" --path ./src

Analyze with JSON output

生成JSON格式的分析结果

python scripts/change_scope_analyzer.py --bug "API returns 500 on empty array input" --path ./src --format json
python scripts/change_scope_analyzer.py --bug "API returns 500 on empty array input" --path ./src --format json

Analyze with specific file extensions

指定文件扩展名进行分析

python scripts/change_scope_analyzer.py --bug "CSS overflow on mobile" --path ./src --extensions .css .scss .html
undefined
python scripts/change_scope_analyzer.py --bug "CSS overflow on mobile" --path ./src --extensions .css .scss .html
undefined

Tools Overview

工具概述

ToolPurposeKey Flags
change_scope_analyzer.py
Identify minimal files to change for a bugfix
--bug
, 
--path
, 
--extensions
, 
--format
工具用途关键参数
change_scope_analyzer.py
确定bug修复需要修改的最小文件集
--bug
, 
--path
, 
--extensions
, 
--format

change_scope_analyzer.py

change_scope_analyzer.py

Analyzes a bug description against a codebase to identify:
  • Files most likely related to the bug (keyword matching, import tracing)
  • Estimated change scope (number of files, lines)
  • Risk assessment for the change
  • Recommended fix approach (minimal vs. structural)
针对代码库分析bug描述，识别以下内容：
  • 最可能与bug相关的文件（关键词匹配、导入追踪）
  • 预估改动范围（文件数量、代码行数）
  • 改动风险评估
  • 推荐修复方式（最小改动vs结构化修复）

Workflows

工作流程

Focused Bugfix Workflow

针对性Bug修复工作流程

  1. Write a clear bug description — reproduction steps, expected vs actual behavior
    • Validate: the description names the observable failure, not a guess at the cause
  2. Run 
    change_scope_analyzer.py
    to identify scope
    • Validate: analyzer output lists concrete files and an estimated line count
  3. Review the recommended files and approach
    • Validate: recommended approach is "minimal" — if it says "structural", stop and scope a refactor PR separately
  4. Make ONLY the changes needed to fix the bug
    • Validate: 
      git diff --stat
      matches (or is smaller than) the analyzer's recommendation
  5. Verify no unrelated changes leaked in
    • Validate: 
      git diff
      shows no formatting-only changes, no unrelated imports, no "while I'm here" edits
  6. Submit PR with focused change set
    • Validate: commit message states the exact bug fixed, and a regression test is included
  1. 编写清晰的bug描述 —— 包含复现步骤、预期行为与实际行为
    • 验证: 描述应明确可观察到的故障，而非对原因的猜测
  2. 运行
    change_scope_analyzer.py
    确定范围
    • 验证: 分析输出列出具体文件和预估代码行数
  3. 审查推荐的文件和修复方式
    • 验证: 推荐方式为“最小改动”——如果显示“结构化”，请停止并单独创建重构PR
  4. 仅进行修复bug所需的改动
    • 验证: 
      git diff --stat
      的结果与分析器推荐的范围一致（或更小）
  5. 确认无无关改动混入
    • 验证: 
      git diff
      显示无仅格式更改、无无关导入、无“顺带”编辑
  6. 提交包含针对性改动集合的PR
    • 验证: 提交信息明确说明修复的具体bug，并包含回归测试

Scope Validation

范围验证

  1. After making changes, re-run analyzer
  2. Compare actual changes against recommended scope
  3. Flag any out-of-scope modifications for separate PRs
    • Validate: any file touched that was not in the analyzer recommendation has a one-line justification or is reverted
  1. 完成改动后，重新运行分析器
  2. 对比实际改动与推荐范围
  3. 将任何超出范围的修改标记为单独PR
    • 验证: 任何未在分析器推荐列表中的修改文件，需提供一行理由或撤销改动

Reference Documentation

参考文档

  • Focused Fix Methodology - Principles, anti-patterns, and decision framework
  • Focused Fix 方法论 - 原则、反模式与决策框架

Common Patterns

常见模式

Do

应该做

  • Fix the exact bug reported
  • Add a regression test for the fix
  • Document why the fix works in the commit message
  • Keep the diff as small as possible
  • 修复报告的具体bug
  • 为修复添加回归测试
  • 在提交信息中记录修复的原理
  • 尽可能缩小差异范围

Don't

不应该做

  • Refactor surrounding code during a bugfix
  • Fix "nearby" issues in the same PR
  • Change formatting or style in touched files
  • Add features disguised as bugfixes
  • 在bug修复期间重构周边代码
  • 在同一个PR中修复“附近”的问题
  • 修改涉及文件的格式或样式
  • 以bug修复为幌子添加新功能

Anti-patterns

反模式

Anti-patternFailure modeFix
"While I'm here" refactors in the bugfix PRBlast radius explodes; review time multiplies; unrelated regressions masked by the real fixOpen a separate PR for the refactor, tagged as 
refactor:
not 
fix:
Reformatting or auto-save style changes in touched filesDiff becomes unreadable; real fix hidden in 200 lines of whitespaceRevert style changes before committing; configure the editor to format-on-save only for new files
Fixing the symptom in the wrong layerBug returns in a new form; accumulates workaround debtTrace to the root layer — analyzer's keyword-match output is a hint, not an answer
Skipping the regression test "because the fix is obvious"Bug silently returns on a refactor 6 months laterEvery 
fix:
commit adds at least one failing-then-passing test
Treating 
change_scope_analyzer.py
output as authoritative		Analyzer is keyword/import-based, not semantic — misses dynamic dispatch, reflection, config-driven pathsUse it as a starting set; grep for callers and tests before committing to the scope
Bundling the fix with a dependency upgradeTwo risk profiles in one PR; if rollback is needed, both are lostLand the upgrade separately, then the fix against the upgraded baseline
反模式失效模式修复方案
在bug修复PR中进行“顺带”重构影响范围扩大；评审时间翻倍；无关回归被真实修复掩盖为重构单独创建PR，标记为
refactor:
而非
fix:
在涉及文件中进行格式化或自动保存的样式更改差异变得难以阅读；真实修复被200行空白更改掩盖提交前撤销样式更改；配置编辑器仅对新文件启用“保存时格式化”
在错误层级修复症状bug以新形式重现；积累 workaround 债务追踪到根源层级——分析器的关键词匹配输出只是提示，而非答案
跳过回归测试“因为修复很明显”6个月后重构时bug悄悄重现每个
fix:
提交至少添加一个先失败后通过的测试
将
change_scope_analyzer.py
的输出视为权威		分析器基于关键词/导入，而非语义——会遗漏动态调度、反射、配置驱动路径将其作为起始集合；提交前搜索调用者和测试用例
将修复与依赖升级捆绑在一起一个PR包含两种风险；如果需要回滚，两者都会丢失先单独合并依赖升级，再基于升级后的基线进行修复