SuperAPI AI Directory

bug-fix-learning

General & other

View repository

Updated 10-15 23:57

About this skill

Bug Fix Learning — Disciplined Fixes and Knowledge Accumulation

Trigger Timing

Encounterany technical problemautomatically triggers, not limited to the user proactively reporting it:

Problems described by the user

  • "found an error," "there's an error here," "this is broken," "it's wrong," "did it wrong," "wrote it wrong"
  • "why is there no XXX," "XXX didn't come out," "XXX doesn't work"
  • "why is this happening," "it should clearly be X but it's Y," "this seems weird"
  • Any description pointing out that code behavior does not match expectations

Situational triggers (the user does not need to say it explicitly)

  • Test failure — tests showing red, assertion error
  • Build failure — compilation error, bundler error
  • Unexpected behavior — the feature runs but the result is wrong
  • Performance issue — obvious performance regression, lag
  • Integration issue — errors when multiple components interact
  • Already tried to fix it but it is not fixed — fixed it once but the problem did not go away, or fixing A broke B

GitHub issue determination

When the user says "help me look at this issue," "handle issue #123," "this ticket," first use gh issue view to read the issue content before classifying:

Issue type Whether it triggers
Bug / defect / regression / "broken, wrong, incorrect" ✅ Must trigger, go through the full process
Feature request / enhancement ❌ Does not trigger, go through the /feature process
Question / usage question ❌ Does not trigger
Documentation ❌ Does not trigger
Refactor / chore ❌ Does not trigger (unless fixing a bug along the way)

Basis for determination: issue label, title keywords (bug、fix、broken、not working、crash、error、regression), whether the body describes "actual behavior vs expected behavior." When ambiguous, prioritize the body; labels may not be correctly applied.

Cases that do not trigger

  • Pure typo, spelling error (just fix it directly)
  • A simple import path error (the IDE / tsc will point it out)
  • A format error in a config file (fix it directly)
  • A feature still under development that was never completed in the first place

Execution process

Step 1: Disciplined fix

Iron Law: If the root cause has not been found, you cannot start changing code. Speculative fixes waste time and create new bugs.

1a. Root cause investigation

Before touching any code, do the following in order:

  1. Read the error message completely — do not skip the error message, stack trace, or warning. They usually tell you the answer directly. Write down the line number, file path, and error code.
  2. Stable reproduction — can it be triggered every time? What are the steps? If it cannot be reproduced, gather more data first; do not guess.
  3. Check recent changes — git diff, recent commits, newly installed dependencies, modified configuration.
  4. Trace the data flow — Where did the bad value come from? Who passed it in? Trace all the way back to the source.Fix at the source, not at the symptom.

Additional steps for multi-component systems: If the system has multiple layers (API → Service → DB, CI → Build → Deploy), add logs at each component boundary, first confirmwhich layer is broken, then dig into that layer to investigate.

Fast track: If the error message directly points to the root cause (e.g., a clear null reference, type error, missing import), you can note the root cause and jump straight to 1d, skipping 1b/1c.

1b. Pattern analysis

  • Find in the codebasesimilar but workingcode
  • Compare what differs between the broken and the working code
  • Do not assume "this doesn't matter" for any difference

1c. Hypothesis and minimal verification

  • State the hypothesis explicitly: "I think the root cause is X, because Y"
  • Makethe minimal changeto verify the hypothesis, changing only one variable at a time
  • Verification fails → propose a new hypothesis,do not stack more fixes on top of the old fix

1d. Implement the fix

  • Fix the root cause, not the symptom
  • Do only one fix at a time, do not refactor along the way
  • Run tests after fixing to confirm

3-strike rule: If you have already attempted 3 fixes and none resolved the problem,stop and question the architecture:

  • Is the pattern itself problematic?
  • Are you solving the problem in the wrong way?
  • Raise an architecture-level discussion with the user, do not attempt a 4th fix

1e. Root cause record

After the fix is complete, record the conclusions of the root cause analysis (for use in Step 2 precipitation evaluation):

  • What was wrong?(the specific erroneous behavior)
  • Why was it wrong?(the root cause)
  • Is this error generalizable?(other developers or future AI may make the same mistake)

Step 2: Evaluate whether it is worth precipitating

For the full positioning of the Cookbook and the three-question criteria, see CLAUDE.md "Quality Gate → Cookbook Sync". Below is a summary of the judgment applicable to this skill.

The Cookbook only collects knowledge that "code, types, tests, import relationshipscannot reveal". Things that can be caught by mechanical tools should not be written, because those rot as the code rots, while mechanical tools do not.

Three-question criteria before writing(if any question is answered "yes", do not write):

  1. Will tsc / eslint catch it? — For example, "changing a signature requires updating the callers in sync". Will catch → do not write, types are the documentation.
  2. Can grep import or deps-check reveal the relationship? — For example, "changing noteService requires syncing NoteList". Can reveal → do not write, rely on dependency checks.
  3. Will the test fail? — For example, "listNotes should return a sorted array". Will fail → do not write, the test is the contract.

Only these categories are worth writing a cookbook for:

A. Bugs and technical pitfalls

  • Implicit coupling across timing/runtime: event ordering, debounce, race condition
  • Pitfalls of external libraries: a certain function in Plate.js crashes when it receives special characters, a certain Firebase API behaves differently in Electron
  • Implicit data contracts: the UI must stay in sync with a certain constant list, but there is no type linkage

B. Business logic

  • Business rules whose why is not visible from the code: show after the sensor has been offline for 30 minutes --(this is defined by the business side, not a technical limitation)
  • Domain-specific calculation logic: the calculation method for yield rate, the data aggregation rules for reports
  • Process constraints: a certain API must be called after another API, a certain state transition has preconditions

C. Architecture decisions

  • The why of historical decisions: why Y is used here instead of X (if background decisions are not written into the code, they will keep being questioned again and again)
  • Reasons for technology choices: why date-fns is used instead of dayjs, why this component does not use a third-party package
  • Design rules that are hard to verify automatically: dark mode color pairings, brand color usage (this type is usually more suitable for CLAUDE.md)

Example comparison:

Content Should a cookbook be written Why
noteService.listNotes returns a Promise ❌ The type is already written
Changing noteService requires changing NoteList ❌ deps-check can catch it
render_widget retries will overwrite agentStorage; debounce is needed ✅ Timing coupling; tsc cannot catch it
Plate.js markdownToSlateNodes crashes when it receives $ crashes ✅ External lib pitfall
OFFICIAL_NOTE_TYPES must stay in sync with the UI menu ✅ Implicit data contract
Show after the sensor has been offline for 30 minutes -- ✅ Business rule; the code does not reveal why it is 30 minutes
Yield rate calculation must exclude the first 10 minutes of warm-up data ✅ Domain knowledge; if the AI does not know it, it will calculate it incorrectly
date-fns is used instead of dayjs because tree-shaking is better ✅ Architecture decision; if not written down, it will keep being questioned again and again
This bug was fixed by changing 3 lines ❌ git log has it
The Button component is placed in src/components/ui/ ❌ grep can find it; writing it down will rot

Important: the three-question criterion is not a "veto right", it is a "router". Answering "yes" means this knowledge should be guarded by mechanical tools, rather than put into the cookbook. Step 4 must tell the user where the knowledge should go (add types, add a lint rule, add tests, or write a cookbook), not simply say "do not write" and stop.

Output your evaluation result:

沉澱評估:
- Cookbook:✅ 需要寫入(原因:...)/ ❌ 不需要(原因:...)
- Memory:✅ 需要寫入(原因:...)/ ❌ 不需要(原因:...)
- Workflow:✅ 需要寫入(原因:...)/ ❌ 不需要(原因:...)

Basis for judging each target:

Accumulation target When to write it in Example
Cookbook(docs/cookbook/) Project-specific development patterns, API usage, component pitfalls, and mistakes that "may be made again next time" Dashboard error handling must be wrapped with ErrorBoundary
Memory(feedback type) Cross-project general development feedback User-preferred confirmation granularity
Workflow(.claude/commands/) Errors caused by process defects Stage 5 has no mandatory completeness check

Can write to multiple targets at the same time.Key: Once you mark ✅ in the evaluation, Step 3 must complete the corresponding write action. The evaluation is to decide "whether to write," not to end after the evaluation is done.

Step 3: Write to file

This is an action step. Your job in this step is to call the Edit or Write tool to write the root cause analysis from Step 1e into the file. If you finish Step 3 but have not called any write tool, then you missed it.

3a. Write to Cookbook

  1. Use Glob to search docs/cookbook/**/*.md, and find the corresponding folder and file based on the modified module
  2. Write business logic to docs/cookbook/<module>/business-rules.md, write pitfall records to docs/cookbook/<module>/pitfalls.md, write architecture decisions to docs/cookbook/architecture/
  3. Use Read to read the document, and use Edit to append the record. If the corresponding folder or file does not exist, use Bash + Write to create it

Example format of the written content:

### 錯誤處理必須包裹 ErrorBoundary

**問題**:Dashboard 模組直接在 template 中呼叫 API,未處理錯誤時整個頁面白屏。

**原因**:模組各自獨立載入資料,但沒有各自的錯誤邊界,一個模組的 API 錯誤會導致整個 Dashboard unmount。

✅ 正確做法:
```vue
<ErrorBoundary>
  <SensorModule :config="config" />
</ErrorBoundary>

❌ Wrong approach:

<SensorModule :config="config" />

#### 3b. 寫入 Memory(若 Step 2 標記為 ✅)

1. 在 memory 目錄建立 `feedback_*.md` 檔案
2. 包含 **Why**(為什麼會犯錯)和 **How to apply**(未來怎麼避免)
3. 更新 `MEMORY.md` 索引

#### 3c. 更新 Workflow(若 Step 2 標記為 ✅)

1. 在對應的 command(如 `feature.md`)加入檢查項目
2. 說明在哪個階段應該攔截此類錯誤

### Step 4:無條件輸出評估摘要

**這是強制步驟,不可跳過**。不論 Step 2 決定寫或不寫,都必須輸出以下格式,讓使用者看到 skill 已經執行完整流程。靜默結束 = 使用者以為 skill 沒觸發,正是此 skill 要避免的失敗模式。

**情境 A:有寫入**(列出實際修改的檔案)

📝 Error learning recorded:

  • Cookbook: docs/cookbook/xxx.md (add ErrorBoundary notes)
  • Memory: no update needed
  • Workflow: no update needed

**情境 B:不需要寫入**(說明為什麼,並建議替代動作)

📝 Error learning evaluation:

  • Cookbook: ❌ Do not write (reason: it is a type contract, and tsc can already guard it)
  • Memory: ❌ Do not write (reason: project-specific, not suitable for cross-project feedback)
  • Workflow: ❌ Do not write
  • Suggested alternative action: in listNotes() add a return type annotation, and tsc will directly block the caller-side type mismatch

「建議替代動作」是 Step 4 的核心——如果 cookbook 不寫,一定要告訴使用者「那該做什麼」。選項包括:

- 補型別 / type guard(tsc 能抓)
- 加 eslint rule(lint 能抓)
- 補單元測試 / E2E 測試(測試能抓)
- 提醒跑 deps-check 確認相依方都看過
- 完全不需要動作(例如純 typo、一次性環境錯誤)

只有當「以上皆不適用」且「下次可能再犯」時,才寫入 cookbook。

## 不沉澱的情況

**預設不寫**。只有通過 Step 2 三問判準的「機械工具抓不到的隱性知識」才寫入 cookbook。常見不寫的情況:

- 純 typo、環境問題、一次性設定錯
- 型別 / eslint / 測試 / deps-check 能抓到的錯(改程式或補測試就夠)
- cookbook 已有相同記錄(此時應反省為什麼沒被攔截,是規則寫不清楚還是沒人讀)
- 純實作細節(例如「這個迴圈改成 for...of 比較快」——改程式就好,不用寫文件)

寫入過多會讓 cookbook 腐爛、沒人讀。寧缺勿濫。