SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbugfix

bugfix

Coding & development

View repository

Updated 10-15 08:13

About this skill

Bug Fix

A test-first Bug fixing workflow, ensuring every fix has regression test protection and complete records.

Quick Start

One-liner: A test-first Bug fixing workflow, ensuring regression protection.

Most Common Usage: /bugfix(automatically assesses complexity after describing the Bug)

Not suitable? New feature →/feature, code quality improvement →/insights

Run Modes

/bugfix                    → 标准修复（自动评估复杂度）
/bugfix BUG-XX realign     → 规范升级回扫：按 BUG-XX 过滤调度相关 skill --realign（仅补齐已完成 bug 流程的规范差距，不触发再修复）

Realign Mode: After a keel spec upgrade, completed bug fix records (BUG-XX entries, tests, fix code) are checked against the new spec_version to fill gaps. Shared contract see ../pipeline/references/realign.md. Scheduling strategy: trace the corresponding F-XX and T-XX by the BUG-XX's 关联 field, delegate /dev-workflow <T-XX> --realign. Recommended user entry /pipeline realign。

Language Rules

  • Supports questions in Chinese and English
  • Unified Chinese replies

Trigger Conditions

  • User reports a Bug or problem
  • User mentions "fix", "bug", "issue", "crash", "error"
  • User provides an Issue number or link
  • Test execution failure (UT/IT/E2E)

Core Principles

先证明 Bug 存在（失败测试），再修复代码，最后证明 Bug 已修复（测试通过）。
每个 Bug 都要记录，形成知识沉淀。

Bug Complexity Assessment

Complexity Characteristics Process
Simple Single file/single function, clear cause Fix directly with this Skill
Complex Multiple modules, needs step breakdown, unclear cause MustGo through /dev-tasks

Workflow

1. 理解 Bug + 评估复杂度
   │
   ├── 复杂 Bug → **必须** /dev-tasks 拆分任务
   │              （用户明确选择"继续简单流程"时除外）
   │
   └── 简单 Bug → 继续
   │
   ▼
2. 定位代码 + 根因确认
   │
   ├── 原因明确 → 继续
   └── 原因不明 → 根因诊断门（见下节）
        ├── 根因证实 → 继续
        └── 连续 2 轮假设全部证伪 → ⚠️ 必须确认
            恢复方式:用户选择转 /dev-tasks 拆分诊断任务,或提供新线索后重进诊断门
   │
   ▼
3. 编写失败测试（证明 Bug 存在）
   │
   ├── 测试通过 → ⚠️ Bug 未复现，重新确认
   └── 测试失败 → ✅ 继续
   │
   ▼
4. 修复代码
   │
   ▼
5. 运行测试
   │
   ├── 测试失败 → 返回步骤 4
   └── 测试通过 → ✅ 继续
   │
   ▼
6. 记录 Bug（追加到 05-bugfix-log.md）
   │
   ▼
7. 询问用户：是否提交？
   │
   └── 生成 fix() 提交信息

Root Cause Diagnosis Gate (must pass when cause is unclear)

Purpose: prohibit "fixing without understanding" (shotgun debugging). Bugs that are simple in scope but have an unclear cause go through this gate and need not be directly escalated to dev-tasks; absorbed conclusions see docs/workflows.md § Coexistence with superpowers。

  1. Reproduction Baseline: Fix stable reproduction conditions (input, environment, steps); if it cannot be stably reproduced → solve reproduction first, do not proceed to hypotheses.
  2. Hypothesis List: List candidate root causes, sorted by likelihood; for each hypothesis state "if it holds, what should be observed". If the environment provides cross-session history retrieval (such as /mem-search), first check "whether the same symptom has been fixed before" (⚠️ include code identifiers such as function name/module name in the query — pure symptom words will be drowned in high-frequency noise, and two actual tests both had zero hits) and rank hit conclusions as the first hypothesis; if that capability is unavailable or no hits are found, infer from the code as usual, ⛔ historical hits do not replace the confirmation in steps 3-4.
  3. Minimal Instrumentation: Perform minimal verification on the preferred hypothesis (targeted logging/breakpoints/minimal experiments),only to falsify or confirm, do not casually change logic。
  4. Falsification Confirmation: Hypothesis confirmed → root cause holds, proceed to failing test (the test assertion should point to that root cause); falsified → cross it out, take the next one; exhausting one round of the list counts as one round.

⛔ Do not continue: starting to fix code before the root cause is confirmed by step 4 Recovery: return to the diagnosis gate to complete confirmation, or follow the ⚠️ escalation branch (switch to /dev-tasks / user provides new clues).

Output Files

Bug Fix Log：docs/devdocs/05-bugfix-log.md

Bug Numbering Rules

Type Prefix Format Description
Bug Record BUG BUG-XXX Bug Fix Record Number

The number continues from the maximum number in the existing document. Scanning method: by id/scan-word-boundary（grep -owhE whole word + sort -n numeric order).

Step 1: Understand the Bug

Collect Bug information:

Information Source Necessity
Bug Description User input Required
Reproduction Steps User input Recommended
Expected Behavior User input Recommended
Actual Behavior User input Required
Discovery Source Test number/Manual testing/User feedback Required
Related Feature F-XXX / AC-XXX, or baseline Required
Issue Number User input Optional

If information is insufficient, use AskUserQuestion to ask.

Bugs in Baseline Projects: Baseline projects (with 00-baseline.md and without 01~04；05-bugfix-log.md and other artifacts do not affect the determination) fix pre-baseline legacy code, which has no F number, andshould not have one temporarily assigned—temporary numbering is the old habit of "deriving conclusions no one ever decided." In this case, fill in "Related Feature" with baseline; regression tests must still be written; traceability goes into the Bug Record on the document side, ⛔ do not write number annotations inside the code.

bugfix/SKILL.md is approaching the 500-line hard limit; this paragraph is an equivalent replacement, do not expand it further.

Complexity Assessment

Use AskUserQuestion to confirm:

根据 Bug 描述，评估复杂度：

[ ] 涉及多个模块/文件
[ ] 原因不明确，需要深入分析
[ ] 修复可能影响其他功能
[ ] 需要多个步骤完成

⚠️ 如以上任一命中，**必须**走 /dev-tasks 拆分任务。
确定要跳过任务拆分，继续简单流程吗？[使用任务拆分(推荐)/继续简单流程]

Step 2: Locate the Code

Search strategy:

  1. Keyword Search: Search for related code based on the Bug description
  2. Error Message Search: Search for keywords in the error message
  3. Test Localization: Locate from the failing test case
  4. User Specification: The user directly provides the file path

Confirm the localization result with the user.

Step 3: Write a Failing Test

Test Naming Convention

should [预期行为] when [触发条件]

Test Structure

describe('Bug fix: BUG-XXX <Bug 描述>', () => {
  it('should <预期行为> when <条件>', () => {
    // Arrange - 构造触发 Bug 的条件
    // Act - 执行操作
    // Assert - 验证预期行为
  });
});

Verify Test Effectiveness

Run the test and confirm the test fails:

  • Test Fails ✅ → Bug reproduced, continue fixing
  • Test Passes ⚠️ → Bug not reproduced, needs re-confirmation

Step 4: Fix the Code

Fixing Principles

  • Minimal Changes: Only modify the necessary code
  • Do Not Introduce New Features: Fix the Bug, do not refactor along the way
  • Follow Existing Style: Stay consistent with the surrounding code

Fixing Constraints

Refer to /code-quality constraints.

Step 5: Run Tests

# 运行新增的 Bug 修复测试
npm test -- --testNamePattern="Bug fix"

# 运行全部测试，确保没有引入回归
npm test
  • New test passes + all tests pass ✅ → Fix complete
  • New test fails → Return to Step 4 and continue fixing
  • Other tests fail → Check whether a regression was introduced

Step 6: Record the Bug

Recording template

Append to docs/devdocs/05-bugfix-log.md：

## BUG-XXX: <Bug 标题>

| 属性 | 内容 |
|------|------|
| **发现来源** | UT-XXX / IT-XXX / E2E-XXX / 手动测试 / 用户反馈 |
| **关联功能** | F-XXX, AC-XXX（或 `baseline`：涉及基线前代码） |
| **Issue** | #123（如有）|
| **严重程度** | P0 / P1 / P2 |
| **修复日期** | YYYY-MM-DD |
| **状态** | ✅ 已修复 |

### 问题描述

<Bug 现象描述>

### 复现步骤

1. <步骤1>
2. <步骤2>
3. <观察到的错误>

### 根因分析

<为什么会出现这个问题，技术层面的原因>

### 解决方案

<如何修复的，修改了什么>

### 回归测试

- 新增测试：UT-XXX / IT-XXX
- 关联 commit：`<commit-hash>`

### 经验教训（可选）

<避免类似问题的建议，供团队参考>

---

Recording key points

Field Description Required
Discovery source Which test/who discovered it Required
Related feature Which feature point is involved (F-XXX / AC-XXX); for existing code before the baseline, fill in baseline Required
Root cause analysis The technical reason Required
Solution How it was fixed Required
Regression test The newly added test ID Required

Step 7: Commit

workspace_context.mode is not inline , the commit follows the N+1 repository protocol (including the detached HEAD pre-gate and cross-repository Recovery), see workspace-topology/references/protocol.md § N+1 repository commit protocol. The code root path is taken from the handshake workspace_context（shared/constraints.md §3 task/workspace-context; when not passed in, use the inline default). The fix code is committed to the corresponding submodule (the commit message follows that repository's style,without the BUG-XX number), and the bugfix log is committed to the shell repository.mode is linked , the code root does not belong to this repository, each repository commits separately, ⛔ do not bump the pointer, see protocol.md §6.5。

Pre-commit checks

  • All tests pass

Commit message format

Follow /commit-convention：

fix(<scope>): <简述问题>

- 根因：<问题原因>
- 修复：<解决方案>
- 测试：<新增测试编号>

BUG-XXX
Fixes #<issue-number>

Example：

fix(auth): handle empty username in login

- 根因：login() 未校验空用户名，直接查询数据库导致异常
- 修复：添加用户名非空校验，返回明确错误信息
- 测试：UT-025

BUG-003
Fixes #123

Closed loop with test cases

测试执行（UT/IT/E2E）
    │
    ├── 通过 → 正常
    │
    └── 失败 → 触发 /bugfix
                    │
                    ├── 记录 BUG-XXX（关联测试编号）
                    │
                    ├── 修复代码
                    │
                    ├── 新增回归测试（更新测试编号）
                    │
                    └── /sync 更新追溯矩阵

Orchestration specification (sub-Agent scheduling)

Under the complex Bug path, when bugfix invokes a sub-skill, itmust start a sub-Agent via the Task tool：

Scenario Scheduled skill Scheduling method
Complex Bug decomposition /dev-tasks Task tool sub-Agent
Complex Bug development /dev-workflow Task tool sub-Agent
Documentation sync /sync Task tool sub-Agent

Scheduling principles

  1. Context isolation: each sub-Agent reads the required documents on its own; the bugfix orchestration layer does not pass the full text
  2. Summary passing: only receive the YAML summary returned by the sub-Agent and decide the next step based on it
  3. Exception fallback: when a sub-Agent returns status: failed + blockers , display the blocking items and ask the user
  4. Do not troubleshoot on your own: the orchestration layer does not read the sub-skill's full output document to try to fix it

Simple Bugs, due to their short flow (single-file fix), are executed directly within the bugfix context without starting a sub-Agent.

Skill collaboration

Scenario Collaborating Skill Description
Complex Bug decomposition /dev-tasks Multi-step Bugs go through task decomposition
Regression test design /test-cases Add regression tests to the test document
Missing requirements /requirements Invoked when a Bug exposes a requirements issue
Test writing /testing-guide Test code quality constraints
Code modification /code-quality Fix code quality constraints
File operations /git-safety Use git mv/rm
Commit message /commit-convention Commit conventions
Documentation synchronization /sync Update traceability matrix after fix

Constraints

Process constraints

  • A failing test must be written first, then the code fixed
  • When the cause is unknown, the root cause diagnosis gate must be passed; only after the root cause is confirmed may fixing begin(shotgun debugging prohibited)
  • ⛔ Do not continue: do not commit when tests are failing(Recovery method: rerun after fixing the failing test)
  • When a complex Bug goes through dev-tasks + dev-workflow, a sub-Agent must be launched via the Task tool

Recording constraints

  • Every Bug must be recorded in 05-bugfix-log.md
  • The discovery source must be recorded
  • The root cause analysis must be recorded
  • The solution must be recorded
  • The regression test number must be linked

Traceability synchronization constraints

  • After the fix is complete, /sync
  • must be executed. New regression tests must be registered in the 03-test-*.md traceability matrix

Test constraints

  • Weak assertions are prohibited (refer to /testing-guide）

Commit constraints

  • The commit message includes the BUG-XXX number

Sub-Agent summary format

When this Skill runs as a sub-Agent, return the following structured summary:

skill: bugfix
status: success | failed | partial
summary:
  headline: "BUG-003 已修复，新增回归测试 UT-025"
  details:
    bug_id: BUG-XXX
    complexity: simple | complex
    related: { feature: F-XXX | baseline, ac: AC-XXX | null }
    test_added: [UT-025]
    commit_hash: "abc1234"
blockers: []
output_files:
  - docs/devdocs/05-bugfix-log.md
new_ids:
  bugs: [BUG-XXX]
  unit_tests: [UT-025]
next_recommended:
  skill: sync

Special cases

Bug cannot be reproduced

⚠️ 测试通过，Bug 未能复现。

可能原因：
1. 复现条件不完整
2. Bug 已在其他提交中修复
3. 环境差异导致无法复现

建议：
- 确认复现步骤是否完整
- 检查最近的相关提交
- 与报告者确认环境信息

Complex Bug

If the Bug involves multiple modules or the cause is unknown:

⚠️ 检测到复杂 Bug，**必须**使用任务拆分：

1. 使用 /dev-tasks 拆分为多个子任务
2. 每个子任务独立修复和测试
3. 最后集成验证

确定要跳过任务拆分吗？[使用任务拆分(推荐)/继续简单流程]

By default, task decomposition must be used; skipping is allowed only when the user explicitly chooses "continue with the simple process".

Bug exposes a design flaw

If the Bug exposes a design issue:

1. 先用最小改动修复当前 Bug
2. 记录设计缺陷到"经验教训"
3. 创建改进建议（可选 /insights）
4. 使用 /refactor 进行系统性改进