bug-fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bug Fix Skill

Bug修复Skill

Diagnose a concrete bug, choose the safest repair path, and fix it — classify complexity first, then either fix directly or track progress through structured phases.

<request_routing>

诊断具体Bug，选择最安全的修复路径并完成修复——先分类复杂度，然后直接修复或通过结构化阶段跟踪进度。

<request_routing>

Positive triggers

正向触发场景

A specific runtime error with a reproduction path, such as
```
Cannot read properties of undefined
```
.
A specific logic bug such as duplicate rendering, stale state, or wrong calculations in one feature.
A concrete API bug with a failing request, response mismatch, or one broken integration path.

带有复现路径的特定运行时错误，例如
```
Cannot read properties of undefined
```
。
特定逻辑Bug，例如某功能中的重复渲染、状态过期或计算错误。
具体的API Bug，包含请求失败、响应不匹配或某条集成路径故障。

Out-of-scope

超出范围

Repository-wide build or CI cleanup. Route that to
```
build-fix
```
.
Security audits, exploit review, or trust-boundary analysis. Route that to
```
security-review
```
.
New feature work, refactors, or speculative cleanup that are not tied to a concrete bug.

仓库范围的构建或CI清理。将此类请求路由至
```
build-fix
```
。
安全审计、漏洞审查或信任边界分析。将此类请求路由至
```
security-review
```
。
与具体Bug无关的新功能开发、重构或推测性清理工作。

Boundary cases

边界情况

If the user asks for root-cause analysis only, stay in diagnosis mode and do not edit.
If the user asks for a direct fix on a single concrete bug, this skill owns it.
If the request starts as a bug but expands into repo-wide build breakage, hand off to
```
build-fix
```
.

</request_routing>

<argument_validation>

If ARGUMENT is missing, ask immediately:

text

Which bug should be fixed?
- Error message / failing symptom
- Expected vs actual behavior
- Reproduction steps
- Related files or call sites
- Recent change, suspect commit, or environment detail

</argument_validation>

<mandatory_reasoning>

如果用户仅要求根因分析，保持诊断模式，不进行代码编辑。
如果用户要求直接修复单个具体Bug，由本Skill负责处理。
如果请求最初是Bug修复，但扩展为仓库范围的构建故障，移交至
```
build-fix
```
处理。

</request_routing>

<argument_validation>

如果缺少ARGUMENT，立即询问：

text

需要修复哪个Bug？
- 错误信息/故障症状
- 预期行为与实际行为对比
- 复现步骤
- 相关文件或调用位置
- 最近的变更、可疑commit或环境细节

</argument_validation>

<mandatory_reasoning>

Mandatory Sequential Thinking

强制顺序思考

Always run

sequential-thinking

before implementation. Depth scales with complexity:

Simple (3 thoughts): Identify cause → determine fix → verify approach
Medium (5 thoughts): Classify → reproduce → hypothesize → compare options → recommend
Complex (7+ thoughts): Classify → reproduce → hypothesize multiple causes → explore dependencies → compare options → assess cross-cutting impact → recommend

Recommended sequence:

Complexity classification
Reproduction and symptom framing
Root-cause hypotheses
Option comparison
Final recommendation

Before any edit, collect root-cause evidence and reduce the problem to a minimal reproduction or the narrowest failing boundary you can actually verify.

</mandatory_reasoning>

<complexity_classification>

实施前必须执行

sequential-thinking

。思考深度随复杂度调整：

简单（3步思考）：确定原因 → 制定修复方案 → 验证方案
中等（5步思考）：分类 → 复现 → 假设 → 对比方案 → 推荐
复杂（7步及以上思考）：分类 → 复现 → 假设多种原因 → 探索依赖关系 → 对比方案 → 评估跨模块影响 → 推荐

推荐流程：

复杂度分类
复现与症状梳理
根因假设
方案对比
最终推荐

在进行任何编辑前，收集根因证据，并将问题简化为可验证的最小复现场景或最窄故障边界。

</mandatory_reasoning>

<complexity_classification>

Complexity Classification

复杂度分类

Classify immediately after sequential-thinking:

Complexity	Signals	Path
Simple	Single file, clear error message, obvious root cause, one fix path, low risk	Fix-now — proceed directly without flow tracking
Complex	Cross-cutting bug, multiple potential root causes, requires investigation across systems, fix has side effects, multiple valid fix strategies	Tracked — create `.hypercore/bug-fix/flow.json`

Announce the classification:

Complexity: [simple/complex] — [one-line reason]

When uncertain, classify as complex. It is cheaper to track than to lose investigation progress.

</complexity_classification>

<flow_tracking>

执行sequential-thinking后立即进行分类：

复杂度	判断信号	处理路径
简单	单文件、错误信息明确、根因明显、仅一种修复路径、低风险	立即修复 — 直接处理，无需流程跟踪
复杂	跨模块Bug、存在多种潜在根因、需要跨系统调查、修复存在副作用、多种有效修复策略	跟踪处理 — 创建 `.hypercore/bug-fix/flow.json`

需告知分类结果：

复杂度: [simple/complex] — [一句话原因]

若不确定，归类为复杂。跟踪流程的成本远低于丢失调查进度的损失。

</complexity_classification>

<flow_tracking>

Flow Tracking (Complex Path Only)

流程跟踪（仅复杂路径）

When classified as complex, initialize the flow:

bash

mkdir -p .hypercore/bug-fix

Write

.hypercore/bug-fix/flow.json

and update it as each phase progresses. See

references/flow-schema.md

for the full schema.

当归类为复杂时，初始化流程：

bash

mkdir -p .hypercore/bug-fix

写入

.hypercore/bug-fix/flow.json

并在每个阶段推进时更新。完整 schema 请参考

references/flow-schema.md

。

Phase progression

阶段推进

Phase	Description	Next
`diagnose`	Reproduce, isolate root cause, collect evidence	`options`
`options`	Present 2-3 fix options with tradeoffs	`confirm`
`confirm`	Wait for and record user selection	`fix`
`fix`	Implement selected option	`verify`
`verify`	Run validation, report outcome	done

阶段	描述	下一阶段
`diagnose`	复现、隔离根因、收集证据	`options`
`options`	提供2-3种带有取舍的修复方案	`confirm`
`confirm`	等待并记录用户选择	`fix`
`fix`	实施选中的方案	`verify`
`verify`	执行验证、报告结果	done

Resume support

续支持

.hypercore/bug-fix/flow.json

already exists, read it first and continue from the last incomplete phase (

in_progress

pending

). Do not restart completed phases.

</flow_tracking>

<execution_modes>

Use one of these branches explicitly:

Diagnose-only: reproduce, isolate the failing path, summarize evidence, and stop before code edits.
Fix-now (simple path): If the user explicitly asks for a direct fix and one path is clearly the safest, say which path you are taking and implement without a second confirmation round. No flow tracking.
Option-first (complex path): present 2-3 repair options with flow tracking and wait for user selection.
Handoff: route repo-wide build breakage to
```
build-fix
```
and security review requests to
```
security-review
```
.

</execution_modes>

如果

.hypercore/bug-fix/flow.json

已存在，先读取该文件并从最后一个未完成阶段（

in_progress

或

pending

）继续。不要重启已完成的阶段。

</flow_tracking>

<execution_modes>

明确使用以下分支之一：

仅诊断：复现、隔离故障路径、总结证据，不进行代码编辑。
立即修复（简单路径）：如果用户明确要求直接修复且某一路径明显最安全，告知将采用的路径并直接实施，无需二次确认。无需流程跟踪。
先出方案（复杂路径）：提供2-3种修复方案并跟踪流程，等待用户选择。
移交：将仓库范围的构建故障路由至
```
build-fix
```
，将安全审查请求路由至
```
security-review
```
。

</execution_modes>

Simple Path (Fix-now)

简单路径（立即修复）

Step	Task	Tool
1	Validate input, sequential-thinking (3 thoughts)	sequential-thinking
2	Classify as simple	-
3	Explore relevant code, identify root cause	Read/Grep/Glob
4	Announce fix path and implement	Edit
5	Run validation (typecheck/test/build)	Bash
6	Report outcome and changed files	-

步骤	任务	工具
1	验证输入，执行sequential-thinking（3步思考）	sequential-thinking
2	归类为简单	-
3	探索相关代码，确定根因	Read/Grep/Glob
4	告知修复路径并实施	Edit
5	执行验证（类型检查/测试/构建）	Bash
6	报告结果及修改文件	-

Complex Path (Option-first)

复杂路径（先出方案）

Step	Task	Tool
1	Validate input, sequential-thinking (7+ thoughts)	sequential-thinking
2	Classify as complex, create `.hypercore/bug-fix/flow.json`	Write
3	Deep investigation → update flow `diagnose: completed`	Read/Grep/Glob + Edit
4	Present 2-3 fix options → update flow `options: completed`	Edit
5	Wait for user selection → update flow `confirm: completed`	Edit
6	Implement selected option → update flow `fix: completed`	Edit/Write
7	Run validation → update flow `verify: completed`	Bash + Edit
8	Report outcome, set flow status to `completed`	Edit

</workflow>

<option_presentation>

Use this format (complex path):

markdown

undefined

步骤	任务	工具
1	验证输入，执行sequential-thinking（7步及以上思考）	sequential-thinking
2	归类为复杂，创建 `.hypercore/bug-fix/flow.json`	Write
3	深度调查 → 更新流程 `diagnose: completed`	Read/Grep/Glob + Edit
4	提供2-3种修复方案 → 更新流程 `options: completed`	Edit
5	等待用户选择 → 更新流程 `confirm: completed`	Edit
6	实施选中的方案 → 更新流程 `fix: completed`	Edit/Write
7	执行验证 → 更新流程 `verify: completed`	Bash + Edit
8	报告结果，将流程状态设置为 `completed`	Edit

</workflow>

<option_presentation>

使用以下格式（复杂路径）：

markdown

undefined

Bug Analysis Result

Bug分析结果

Root cause: ... Impact scope: ... Complexity: complex

根因: ... 影响范围: ... 复杂度: complex

Option 1: ... (Recommended)

方案1: ...（推荐）

Pros:
Cons:
Risk:
Files:

优势:
劣势:
风险:
涉及文件:

Option 2: ...

方案2: ...

Pros:
Cons:
Risk:
Files:

优势:
劣势:
风险:
涉及文件:

Option 3: ... (Temporary)

方案3: ...（临时）

Pros:
Cons:
Risk:
Files:

Recommendation: Option N (reason ...) Which option should I apply? (1/2/3)


</option_presentation>

<implementation_rules>

- Do not modify code before user option selection unless in the explicit Fix-now branch.
- Avoid speculative edits; use evidence-based fixes only.
- Keep scope limited to the requested bug and direct impact.
- Always run targeted validation for the changed path, not just a generic command dump.
- Report the commands run, the key result lines, and the touched files in the final report.
- If validation cannot run, say why and what remains unverified.

优势:
劣势:
风险:
涉及文件:

推荐方案: 方案N（原因...）应采用哪个方案？(1/2/3)


</option_presentation>

<implementation_rules>

- 除非处于明确的立即修复分支，否则在用户选择方案前不得修改代码。
- 避免推测性编辑；仅采用基于证据的修复。
- 修复范围仅限请求的Bug及其直接影响。
- 始终针对修改路径执行定向验证，而非仅执行通用命令。
- 在最终报告中记录执行的命令、关键结果行及修改的文件。
- 如果无法执行验证，说明原因及未验证的内容。

Reporting

报告要求

After execution, report:

markdown

undefined

执行完成后，提交报告：

markdown

undefined

Done

完成

Bug: [original symptom] Root cause: [what was wrong] Fix applied: [which option or approach] Changes: [list of changed files] Validation: [what was verified and result]


For complex path: also update `.hypercore/bug-fix/flow.json` status to `completed`.

</implementation_rules>

<validation>

Execution checklist:

- [ ] ARGUMENT validated
- [ ] sequential-thinking completed (depth matches complexity)
- [ ] Complexity classified (simple/complex)
- [ ] Flow JSON created and maintained (complex path only)
- [ ] Root-cause evidence collected
- [ ] 2-3 options presented (complex path) or fix path announced (simple path)
- [ ] User choice confirmed (complex path)
- [ ] typecheck/test/build executed
- [ ] outcome + touched files reported
- [ ] Flow JSON finalized with `completed` status (complex path only)

Forbidden:

- [ ] speculative fix without evidence
- [ ] immediate implementation without options (complex path)
- [ ] implementation without explicit user choice (complex path)
- [ ] completion claim without validation
- [ ] skipping flow JSON updates in complex path

</validation>

Bug: [原始症状] 根因: [问题所在] 应用的修复: [采用的方案或方法] 修改内容: [修改文件列表] 验证情况: [验证内容及结果]


对于复杂路径：还需将`.hypercore/bug-fix/flow.json`的状态更新为`completed`。

</implementation_rules>

<validation>

执行检查清单：

- [ ] ARGUMENT已验证
- [ ] sequential-thinking已完成（思考深度匹配复杂度）
- [ ] 复杂度已分类（simple/complex）
- [ ] 流程JSON已创建并维护（仅复杂路径）
- [ ] 根因证据已收集
- [ ] 已提供2-3种方案（复杂路径）或告知修复路径（简单路径）
- [ ] 用户选择已确认（复杂路径）
- [ ] 已执行类型检查/测试/构建
- [ ] 已报告结果及修改文件
- [ ] 流程JSON已最终设置为`completed`状态（仅复杂路径）

禁止事项：

- [ ] 无证据的推测性修复
- [ ] 未提供方案直接实施（复杂路径）
- [ ] 未获得用户明确选择即实施（复杂路径）
- [ ] 未验证即声称完成
- [ ] 复杂路径中跳过流程JSON更新

</validation>