devdocs-bugfix

Bug Fix

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

Language Rules

Support questions in Chinese and English
Reply uniformly in Chinese

Trigger Conditions

The user reports a Bug or issue
The user mentions "fix", "bug", "issue", "crash", "error"
The user provides an Issue number or link
Test execution fails (UT/IT/E2E)

Core Concept

先证明 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 `/devdocs-dev-tasks`

Workflow

1. 理解 Bug + 评估复杂度
   │
   ├── 复杂 Bug → **必须** /devdocs-dev-tasks 拆分任务
   │              （用户明确选择"继续简单流程"时除外）
   │
   └── 简单 Bug → 继续
   │
   ▼
2. 定位代码
   │
   ▼
3. 编写失败测试（证明 Bug 存在）
   │
   ├── 测试通过 → ⚠️ Bug 未复现，重新确认
   └── 测试失败 → ✅ 继续
   │
   ▼
4. 修复代码
   │
   ▼
5. 运行测试
   │
   ├── 测试失败 → 返回步骤 4
   └── 测试通过 → ✅ 继续
   │
   ▼
6. 记录 Bug（追加到 05-bugfix-log.md）
   │
   ▼
7. 询问用户：是否提交？
   │
   └── 生成 fix() 提交信息

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

Numbers continue from the maximum number in existing documents.

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	Required
Issue number	User input	Optional

If information is insufficient, use AskUserQuestion to ask.

Complexity Assessment

Use AskUserQuestion to confirm:

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

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

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

Step 2: Locate the Code

Search strategy:

Keyword search: search related code based on the Bug description
Error message search: search for keywords in the error message
Test localization: locate from the failing test case
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

/**
 * @verifies AC-XXX   // 关联的验收标准（必须，确保 trace 可追溯）
 * @verifies BUG-XXX  // Bug 编号（保留，用于 Bug 追踪）
 * @testcase UT-XXX
 */
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

Fix Principles

Minimal changes: only modify the necessary code
Do not introduce new features: fix the Bug, do not refactor along the way
Follow the existing style: stay consistent with the surrounding code

Fix constraints

Reference /code-quality constraints.

Step 5: Run tests

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

# 运行全部测试，确保没有引入回归
npm test

New tests pass + all tests pass ✅ → fix complete
New tests fail → 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 |
| **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)	Required
Root cause analysis	The technical cause	Required
Solution	How it was fixed	Required
Regression test	The number of the newly added test	Required

Step 7: Commit

Pre-commit checks

Newly added tests pass
All tests pass
Bug has been recorded in 05-bugfix-log.md
Code complies with the standards

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）
    │
    ├── 通过 → 正常
    │
    └── 失败 → 触发 /devdocs-bugfix
                    │
                    ├── 记录 BUG-XXX（关联测试编号）
                    │
                    ├── 修复代码
                    │
                    ├── 新增回归测试（更新测试编号）
                    │
                    └── /devdocs-sync 更新追溯矩阵

Orchestration standards (sub-agent scheduling)

On complex bug paths, when devdocs-bugfix calls sub-skills,sub-agents must be launched via the Task tool：

Scenario	Scheduled skill	Scheduling method
Complex bug decomposition	`/devdocs-dev-tasks`	Task tool sub-agent
Complex bug development	`/devdocs-dev-workflow`	Task tool sub-agent
Documentation sync	`/devdocs-sync`	Task tool sub-agent

Scheduling principles

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

Because the simple bug flow is short (single-file fix), it is executed directly in the bugfix context without launching a sub-agent.

Skill collaboration

Scenario	Collaborating skill	Description
Complex bug decomposition	`/devdocs-dev-tasks`	Multi-step bugs go through task decomposition
Regression test design	`/devdocs-test-cases`	Add regression tests to the test document
Missing requirements	`/devdocs-requirements`	Invoked when a bug exposes a requirements problem
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 sync	`/devdocs-sync`	Update traceability matrix after fix

Constraints

Process constraints

Must write failing test first, then fix the code
The test must fail first, proving the Bug exists
The test must pass after the fix
Must not skip tests and commit directly
For complex Bugs going through dev-tasks + dev-workflow, child Agents must be started via the Task tool
Simple Bugs are executed directly within the bugfix context

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 ID must be linked

Traceability sync constraints

After the fix is complete, must execute /devdocs-sync
Newly added regression tests must be registered in the 03-test-*.md traceability matrix
If trace is not executed, the Bug fix becomes a "bypass" and tests cannot be traced

Test constraints

The test name describes the Bug scenario
The test covers the Bug's trigger conditions
The test must add a @verifies AC-XXX annotation (the associated acceptance criterion, ensuring trace is traceable)
The test must add a @verifies BUG-XXX annotation (Bug number)
Weak assertions are prohibited (refer to /testing-guide）

Commit constraints

The commit message uses the fix(<scope>): prefix
The commit message includes the BUG-XXX number
Link the Issue number (if any)

Child Agent summary format

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

skill: devdocs-bugfix
bug_id: BUG-XXX
complexity: simple | complex
status: fixed | not_reproduced | in_progress
related: { feature: F-XXX, ac: AC-XXX }
test_added: [UT-025]
commit_hash: "abc1234"
output_file: docs/devdocs/05-bugfix-log.md

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. 使用 /devdocs-dev-tasks 拆分为多个子任务
2. 每个子任务独立修复和测试
3. 最后集成验证

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

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

Bug exposes a design flaw

If the Bug exposes a design problem:

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