诊断

工程开发 社区

技能解读

设计思路

diagnose 是 mattpocock 总结的「Bug 诊断六阶段」工作流,把模糊的「调一下」拆成结构化的从假设到根因的链路。先建 feedback loop,再下诊断结论——所有阶段都基于「能稳定复现」这个前提。

六个阶段(按作者原文)

  • Phase 1:Build a feedback loop 把 bug 变成一个可以一次次跑、跑得快、信号明确的 reproducer。没这个就不要往下走。
  • Phase 2:Reproduce 最小化复现路径——剥掉一切非必要因素,让信号清晰。
  • Phase 3:Hypothesise 列出假设并按可能性排序;问用户有没有自己的怀疑("jump to #3")或已经排除过哪些——便宜的 checkpoint,省时间。用户 AFK 就先按你自己的排序往下走。
  • Phase 4:Instrument
    • 每个 probe 都要对应一个具体假设。
    • 一次只改一个变量。
    • 工具优先级:debugger / REPL > 边界处的 targeted log >「全打 log 再 grep」(最次)。
    • 每条 debug log 都打唯一前缀(如 [DEBUG-a4f2]),结尾一次性 grep 清干净——untagged 留下,tagged 死掉。
    • 性能问题分支:log 通常不对路,先建立 baseline 测量(timing harness、performance.now()、profiler、query plan)再 bisect——先量后修。
  • Phase 5:Fix + regression test
    • 先写回归测试再写 fix——但只在「正确缝隙」存在时。
    • 「正确缝隙」= 测试覆盖到真实 bug 模式发生的那个调用点。
    • 如果只有过浅的缝隙(单 caller 写测试 / 单元测试无法复现 chain)——这本身就是发现:架构在阻碍 bug 被锁定,记下来交给 improve-codebase-architecture。
    • 有正确缝隙时:把 minimised repro 变成 failing test → 看它失败 → 应用 fix → 看它通过 → 用 Phase 1 loop 在原始(未最小化)场景再跑一次。
  • Phase 6:Cleanup + post-mortem 完成清单:原始复现已不再复现 / 回归测试通过(或缝隙缺失被记下)/ 所有 [DEBUG-...] 都 grep 清掉 / 临时 prototype 删掉或挪到明确的 debug 目录 / commit 或 PR 写明「最终被验证的假设」让下一个调试者受益。 再问一句:如果答案涉及架构改动(缺好缝隙、调用方纠缠、隐藏耦合),把这个交给 improve-codebase-architecture skill——但修完之后才提,因为现在你比开始时知道得多。

适合谁

  • 接到「线上偶现」类 bug 的工程师
  • 性能回归调查(务必走 perf 分支)
  • 想把调试经验做成可教学的教练 / Tech Lead

不适合

  • 一眼能看出来的低级错误——直接改
  • 没有可重复跑的环境——先去搭,否则 Phase 1 都过不去

配套

systematic-debugging(更基础的姊妹工作流)、improve-codebase-architecture(Phase 5 / 6 暴露架构问题时的下一站)、tdd(缝隙存在时的回归测试母法)。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
94 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@MorphiaOrg · Apache-2.0
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
macOS
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Diagnose Test Failure

## Overview

Systematic diagnosis of test failures in the Morphia project. Run the test, read the full error, trace the root cause through source and generated code, fix minimally, and verify.

## Workflow

1. **Run the failing test**
   ```
   ./mvnw test -pl :module-name -Dtest="ClassName#methodName" -Ddeploy.skip=true
   ```
   - Use `-Ddeploy.skip=true` to skip dokka
   - Do NOT use `-am` with `-Dtest=` (applies test filter to all modules)
   - If dependencies need rebuilding first:
     ```
     ./mvnw install -pl :dep1,:dep2 -DskipTests -Ddeploy.skip=true -Dinvoker.skip=true
     ```

2. **Read the full error** - stack trace, error message, line numbers. Don't skip anything.

3. **Find relevant code** - Read both source AND generated code:
   - Source: `src/main/`, `src/test/`
   - Generated bytecode: `target/test-classes/` - use `javap -c -p ClassName` to decompile
   - Generated sources: `target/generated-sources/`
   - Interfaces from dependencies: check `~/.m2/repository/` source jars with `unzip -p`

4. **Trace the root cause** - Follow the error backward:
   - What method is missing/wrong?
   - What generated it? (Gizmo generator? ASM generator?)
   - What does the interface/superclass require?
   - Compare with working examples (ASM-based generators have bridge methods; check if Gizmo-based ones do too)

5. **Fix minimally** - One change at a time. Rebuild affected modules:
   ```
   ./mvnw install -pl :critter-core,:critter-maven -DskipTests -Ddeploy.skip=true -Dinvoker.skip=true
   ```

6. **Verify** - Re-run the failing test AND related tests in the same class.

## Common Morphia/Critter Issues

| Error | Likely Cause |
|-------|-------------|
| `AbstractMethodError` | Missing bridge methods in generated bytecode (generic interface erasure) |
| `Cannot checkcast to primitive` | Gizmo `checkCast` doesn't work on primitives - use `smartCast` |
| `Cannot convert primitive to Object` | Need boxing: `smartCast(result, wrapperType)` |
| `NoSuchMethodError __read*/__write*` | Accessor methods not generated on entity class |
| `ClassNotFoundException __morphia.*` | Critter code generation didn't run or class not registered |

## Key Gotchas

- Gizmo does NOT auto-generate bridge methods for generic interfaces
- Primitive types need explicit boxing/unboxing via `smartCast`
- `checkCast(Object -> wrapper)` then `smartCast(wrapper -> primitive)` for unboxing
- `smartCast(primitive -> wrapper)` for boxing
- Always check both Gizmo (`parser/gizmo/`) and ASM (`parser/asm/`) generators for patterns

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。