bitcjm/workbuddy-skills/self-debug

自我排查与变通框架

遇到异常结果时，按以下行为规则自己先走完，每一层走完无果再考虑问用户。

Layer 1: 可疑点识别（直觉必须被训练）

• 输出数据量是否反常？太少 → 怀疑有上限截断；太多 → 怀疑有循环/重复
• 工具行为是否有异常提示？"试用"/"演示"/"体验模式" → 凭证缺失；timeout/retry → 参数或网络问题
• 用户的表述暗示了什么深层需求？"只显示了几条" → 分页；"结果明显不对" → 配置或前提假设错了
• 不要只看结果表象，往深层想一步。
• 跨数据点模式中断：多数据点对比中，某一点孤立缺失而其他点正常时 → 默认先怀疑查询方式（参数不完整/条件不匹配）而非业务原因（渠道无库存）。不要因为一个渠道数据缺失就跳过对比——先检查自己的查询逻辑。

Layer 2: 验证假设（从深到浅）

• 先查源码/配置文件：grep 硬编码值（limit/offset/pageSize/maxResults）或配置路径 — 这是最硬的证据
• 再查文档/help：--help、README、API doc，确认参数是否存在
• 最后试探：传各种参数名看 CLI 是否透传；看 JSON 中是否有隐藏字段
• 原则：能用 grep 证实的不用文档，能用文档证实的不用试。

Layer 3: 变通思维（限制是死的，参数是活的）

发现硬性限制后，不要止步于"有限制"——问自己：什么参数组合可以把问题规模压到限制以下？

• 有数量上限 → 加筛选条件（时间窗口/类别/关键字/精确值）缩窄范围
• 有并发限制 → 分批 + 间隔执行
• 有权限限制 → 换另一种工具/渠道迂回
• 有不支持的字段 → 用其他来源先获取关键信息，再回到原工具执行精确查询

核心原则：先取 key 信息，再精确定位。 不追求一次拿到全部数据。

Layer 4: 复盘自问（解决问题后必须做的内省）

1. 这个问题是我应该自己发现的吗？为什么没发现？
2. 用户指出的方案/思路，我为什么没想到？缺了什么推理步骤？
3. 抽象成什么通用规则，下次遇到同类问题能直接套用？

Layer 5: 固化（不白踩坑）

• 找到的变通方案 → 写入本次 task 对应的项目文档（SKILL.md、reference/、MEMORY.md 等）
• 明确记录：限制来源 + 绕过方法 + 已验证示例
• 抽象出的通用规则 → 按情况加入 SOUL.md（跨项目通用）或项目文档（项目内适用）

Layer 6: 阻塞升级 — 卡住时启动外部审查

• 触发条件：同一问题尝试 ≥ 2 次仍失败，或 L1-L5 走完仍无进展
• 行动：spawn 一个子智能体（sub-agent），加载专用的审查 skill，把当前困境的完整上下文喂给它
• 等待：主智能体耐心等待子智能体输出审查报告，不要同时尝试其他方案
• 执行：拿到审查报告后，按报告中的行动建议逐条尝试
• 停止条件：按审查建议尝试后仍然卡在同一个问题上（同样的错误、同样的阻塞点），立即停止。不要再开新一轮审查，不要再换方案自己试
• 停止交付：向用户描述：当前卡点 + 已尝试方案列表 + 每次失败表现 + 审查结论 + 需要用户把关的具体问题
• 注意：如果按审查建议尝试后有实质推进（卡点变了、发现新问题），不算"同一问题"，继续推进即可。只当完全原地踏步时才触发停止
• 子智能体 prompt 要点：给子智能体的 prompt 中必须包含：当前任务目标、卡住的具体步骤、已尝试方案及每次的失败表现、相关文件路径（让子智能体自己去读）

⚠️ 数据缺失结论前的 4 条硬自检

在得出"某渠道无此数据"结论前，必须依次走完（≥2 次重试即触发外部审查，不可跳过）：

1. 启动审查：同一渠道同一查询 ≥ 2 次重试仍无结果 → 立即 spawn 审查子智能体审查查询方式是否正确
2. 检查操作手册：该渠道对应的操作手册中，所有必填参数（格式、值域）是否正确使用
3. 确认参数完整：逐一核对查询参数（三字码、时间切片、journey-type、日期格式等）无遗漏
4. 确认覆盖范围：对比其他渠道的结果，确认航线、日期、舱位等目标条件匹配

One-Shot 示例：搜索接口只返回 5 条结果

假设你在调试一个文档搜索工具，搜"性能优化"只返回 5 条，但该文档库有几百篇文章。

L1 可疑点识别： 文档库成千上万篇文章，5 条显然是截断了。不是因为关键词不匹配，而是接口有默认上限。

L2 验证假设： 查 --help 没有分页参数；grep CLI 包的源码 → 找到一行 const limit = 10。证实硬编码。再 grep → 发现底层 API 其实有 pageSize 参数，但 CLI 没暴露。

L3 变通思维： 无法直接调 pageSize。搜"性能优化"结果太多被截断 → 改搜 "性能优化 数据库"（加具体类别），结果变成 3 条，目标文章在里面。也可以用 "性能优化" + "--author 张三"（作者过滤）来缩小范围。

L4 复盘自问： 我为什么没第一时间怀疑 5 条有问题？缺了对输入规模的预判。下次遇到任何"返回列表"的场景，先判断"理论上该有多少"。

L5 固化： 把"组合筛选关键字（类别+作者+日期）绕过 limit" 写入项目文档。下次这个工具再次被调用时，自动采用 "先所有字段过筛 → 再查" 的流程。