Back to Details

debug-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debug Loop

调试循环

Autonomous hypothesis-driven debugging against real data. No guessing, no simulating.
基于真实数据的自主假设驱动调试。无需猜测，无需模拟。

Arguments

参数

  • <symptom>
    — Description of the bug or unexpected behavior. If omitted, prompt the user.
  • <symptom>
    — 问题或异常行为的描述。如果省略，需提示用户补充。

Phases

阶段

Phase 1 — Reproduce

阶段1 — 复现

Run the exact command that shows the bug. Capture and display the REAL output. Confirm the bug is visible.
If the bug cannot be reproduced, stop and explain what was tried.
运行能复现问题的精确命令。捕获并展示真实输出。确认问题已复现。
如果无法复现问题，请停止操作并说明已尝试的步骤。

Phase 2 — Hypothesize and Test (up to 5 iterations)

阶段2 — 假设与测试（最多5轮迭代）

For each iteration:
  1. State a specific hypothesis (e.g., "the query targets v2 tables but data is in v3 tables")
  2. Run a REAL command to test it (e.g., 
    sqlite3 [db path] '.tables'
    then 
    SELECT COUNT(*) FROM [table]
    )
  3. Record whether the hypothesis was confirmed or rejected
  4. If rejected, form the next hypothesis based on what you learned
Do NOT make code changes until you have a confirmed root cause.
Important checks:
  • Always check both v2 and v3 SQLite tables when data issues are suspected
  • Check dependency versions (e.g., sqlite3 vs better-sqlite3)
  • Check for hardcoded values that may have been missed
每轮迭代需执行以下步骤：
  1. 提出具体假设（例如：“查询针对v2表，但数据实际存储在v3表中”）
  2. 运行真实命令进行测试（例如：
    sqlite3 [数据库路径] '.tables'
    然后执行 
    SELECT COUNT(*) FROM [表名]
    ）
  3. 记录假设是否成立
  4. 如果假设不成立，基于已得信息提出下一个假设
在确认根本原因之前，请勿修改代码。
重要检查项：
  • 当怀疑存在数据问题时，务必同时检查v2和v3 SQLite表
  • 检查依赖版本（例如：sqlite3 vs better-sqlite3）
  • 检查是否存在被遗漏的硬编码值

Phase 3 — Fix

阶段3 — 修复

Make the minimal targeted fix. Explain:
  • What the root cause was
  • What you're changing and why
  • What the blast radius is (which other code paths are affected)
Before applying, grep for ALL instances of the problematic pattern across the entire codebase.
实施最小化的针对性修复。需说明：
  • 问题的根本原因是什么
  • 你要修改的内容及原因
  • 影响范围（即其他哪些代码路径会受影响）
在应用修复前，需在整个代码库中搜索所有存在问题模式的实例。

Phase 4 — Verify

阶段4 — 验证

Run the SAME reproduction command from Phase 1. The output must now show correct values. If it doesn't, go back to Phase 2.
Show before/after output comparison.
运行阶段1中用于复现问题的同一命令。输出必须显示正确结果。如果未达到预期，返回阶段2重新操作。
展示修复前后的输出对比。

Phase 5 — Regression

阶段5 — 回归测试

bash
npm test
Run the full test suite. If tests fail, fix them before committing.
bash
npm test
运行完整测试套件。如果测试失败，需在提交前修复问题。

Rules

规则

  • NEVER guess or simulate output — always run real commands
  • NEVER make code changes before confirming root cause
  • Always check for the pattern across the entire codebase, not just one file
  • If blocked after 5 hypotheses, stop and ask the user for guidance
  • 绝对不要猜测或模拟输出——始终运行真实命令
  • 在确认根本原因之前，绝对不要修改代码
  • 务必在整个代码库中搜索问题模式，而非仅检查单个文件
  • 如果经过5轮假设后仍无法推进，请停止操作并向用户寻求指导