gjalla-debug

用途

gjalla-debug 是一个调试（Debug）技能，其职责是：在修复任何东西之前，先把“实际为真”的情况找出来，并且能够展示排查过程。文档强调，一个自信但错误的诊断比没有诊断代价更高，因为建立在其上的一切都要被拆解回退。

该技能要防范的失败模式是：过早形成理论，然后只读取能印证它的内容。从内部感受上，一次不完整的调查与一次完整的调查完全一样。

主要能力与流程

精确确立症状：在碰代码之前，先确定实际观察到的现象——谁看到、在什么界面、用什么输入、多频繁、从何时开始。“它坏了”和“一次会话中的第二次保存返回了过期数据”会导向完全不同的调查。若报告含糊，第一个有用的产出是更锐利的问题描述，而不是修复。
复现，或明确说明无法复现：运行它。在有条件观察代码实际行为时，不要只靠推理判断代码会做什么。通过阅读来追踪流程，正是 bug 藏身之处：条件分支、描述已不存在代码的过期注释、只在生产环境出现的数据形态。若无法复现，明确说明，并转向不依赖复现的证据：日志、遥测、数据库状态、错误报告。未复现的 bug 仍可诊断，但置信度不同，应如实区分报告。
确认所读内容是最新的：成本很低，但跳过会让整个调查失效。确认检出代码与已部署版本一致，没有在读过期的工作树或 vendored 副本，所参考的缓存产物最近被重新生成过。来自废弃分支的 grep 结果与来自活跃代码的 grep 结果看起来一模一样。
先收集上下文再理论化：查看 gjalla 中已知的信息——规则、记忆和变更历史常常包含你即将重新发现的坑，架构会告诉你哪些组件实际在路径上。可能有人已经碰到过并写下了原因。
区分观察与推断：在自己的笔记和报告中保持二者分离。“响应体为空”是观察。“序列化器丢掉了该字段”是推断。推断需要在代码或数据中得到确认后才能提升为结论；从未被确认的推断在报告时应标注为推断。
找到根因，而非第一个能让症状消失的地方：追问为什么这个坏状态一开始可以被触达，而不只是哪一行产生了它。缺少一个守卫，通常是某个机制无法自然强制该不变量的症状。在反转任何限制、超时、重试次数或预算之前，先查 git 历史和注释以了解意图。这些数字往往是刻意的，其存在源于此前的一次事故。
在代码树中枚举该 bug 的形态：一旦知道缺陷长什么样，就在全仓库范围内 grep 它的形态：未带守卫调用的方法、未被使用的辅助函数、重复出现的模式。然后报告数量。只修好发现的那一处而另外三处存活，下个月会再次被报告。如果该模式跨越服务边界，也检查其他仓库。
证明它：证明你找到了真正原因的，是一个现在失败、修复后通过、且原因正确的测试。在可能的情况下，先写这个测试再修复。如果某个建议的修复不能改变该测试的结果，那么无论故事多么可信，你找的原因就是错的。

输出内容

症状：精确观察到什么，以及在什么条件下。
根因：机制，附 file:line 证据。
为何可被触达：是什么允许这种状态存在，而不仅仅是它在哪里浮现。
影响范围：该形态出现的其他所有位置，逐条枚举并给出数量。
置信度：哪些是直接验证的、哪些是推断的、哪些无法确定。
建议修复：包括证明它的测试。

如果修复不简单或触及系统原语，到此停下，交由 gjalla-spec 处理，而不是直接实现。

适用场景

当某物损坏、行为不符预期，或用户报告了某个问题时使用。它适合需要可追溯证据与根因定位的排障工作，而非以最快速度消除表面症状。

原则与限制

证据优先于推理：能运行、能观察、能查询时，就去做，而不是基于代码争论。
报告你不知道的：“我无法复现，诊断依赖于一行日志”是有用且诚实的发现。安静的自信不是。
bug 很少在它浮现的地方：堆栈跟踪告诉你它在哪里变得可见，而它往往在出错位置的下游若干层。
保存你学到的东西：非显而易见的成因，正是应当写入 gjalla 记忆的内容，这样下一个智能体或下一个你无需重新发现：gjalla memory add "<the fact>" -n "<short-name>"。

暂未提供

本技能的具体运行环境、安装方式、支持平台、是否收费及价格、性能数据等，资料中暂未提供。

分类

category: coding