Menu
系统化 bug 定位：根因调查 → 模式分析 → 假设验证 → 修复。 Use when: 遇到 bug、测试失败、unexpected behavior。 Not for: 新功能开发、重构、已知原因的简单修复。 Output: Bug report（5件套）+ 根因 + 修复（含回归测试）。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
约定图发现方法论：进一个 repo 先识别 repo-specific conventions，再定义 domain/extractor 接 Convention Graph 引擎。Use when: 进入陌生 repo、要画约定图、要找“改 X 影响谁”的约定层关联、 F242/Convention Graph Layer 工作。Not for: 普通符号跳转/LSP、文档索引检索、记忆图谱、直接使用 codegraph/GitNexus。Output: domain 定义 + extractor 计划 + gap/freshness/provenance 报告。 GOTCHA: 沉淀的是“怎么画图”的方法，不是把 cat-cafe 的 extractor 硬搬到所有 repo。
跨 thread 协同：发现平行 session → 通知（3+2 件套）→ 争用协调 → 确认。 Use when: 平行 session 之间需要协同、收到跨线程消息、通知改动影响、共享文件争用。 Not for: 跨猫工作交接（用 cross-cat-handoff）、需要新建 thread 时（用 propose_thread / thread-orchestration）。 GOTCHA: 收到跨线程 ACTION 不等于接活；先做 thread/feat ownership gate，不属于当前 thread 就 cross-post 退回。 Boundary with F128: 发现跨 scope 问题 → 先 list_threads 查有没有已有 thread → 有 = 本 skill（cross_post）→ 没有 = propose_thread。 Output: cross-post 通知 + 争用协调完成。
Feature 立项、讨论、完成的全生命周期管理。 Use when: 开个新功能、new feature、F0xx、立项、feature 完成、验收通过、讨论新功能需求。 Not for: 代码实现、review、merge（那些有专门的 skill）。 Output: Feature 聚合文件 + BACKLOG 索引 + 真相源同步。
明星开源项目拆解：从宣传/PPT/README 进入源码，验证真实架构、明星特性、算法含量、营销水分、可学习点和不 follow 的 tradeoff。 Use when: operator要求拆解热门 GitHub 项目、竞品 agent/runtime、外部 skill/tool 框架，或问“它到底有什么真本事/我们能学什么”。 Not for: 普通资料搜索（用 deep-research）、社区 issue/PR 运营（用 opensource-ops）、只需要架构头脑风暴（用 collaborative-thinking）。 Output: feature-discussions/YYYY-MM-DD-{project}-deep-dive/ 下的代码证据报告 + 对比结论 + 候选 lesson/skill。 GOTCHA: 不许只看 README 下判断；每个明星特性必须追到代码路径、状态突变点、反馈闭环和算法输入输出。
开发完成后的自检门禁：愿景对照 + spec 合规 + 验证。 Use when: 开发完了准备提 review、声称完成了、准备交付。 Not for: 收到 review 反馈（用 receive-review）、merge（用 merge-gate）。 Output: Spec 合规报告（含愿景覆盖度）。
接球前真相核验三问：claim → resolver → verdict (sourceTier T0/T1/T2 + actionFamily)， 防止把传球者当无审视真相源（F167 Phase O 第一性原理）。 Use when: 即将调 hold_ball / register_pr_tracking / register_issue_tracking / merge / takeover / 改 owner / 任何 irreversible action / 基于 "operator signoff" 或 "你是 owner" 类 claim 行动之前。 Not for: 纯阅读 cross_post（无 actionFamily 后续）；本 thread 日常 @mention 无副作用； implementation continuation（自检通过的下一步）。 Output: claim grounding verdict (verified/mismatch/insufficient) + 接球决策 (proceed / block / push back to source thread)。
| name | debugging |
| description | 系统化 bug 定位：根因调查 → 模式分析 → 假设验证 → 修复。 Use when: 遇到 bug、测试失败、unexpected behavior。 Not for: 新功能开发、重构、已知原因的简单修复。 Output: Bug report（5件套）+ 根因 + 修复（含回归测试）。 |
| triggers | ["bug","报错","test failure","unexpected behavior"] |
随机尝试修复浪费时间，症状修复掩盖真正问题。
遇到 bug 先搜（F102 记忆系统）：search_evidence("{error关键词}") 看看历史上有没有类似的坑。
铁律：没有根因分析，不能提出修复方案。
如果 bug 涉及 runtime 行为（前端显示异常、API 返回错误、猫猫行为异常、stream 错误等），在进入 Phase 1 之前必须先完成三件套验证：
手动三件套（按顺序执行，收集 7 个字段）：
# 1. 找到 API 监听进程（绑端口，不用 grep 猜）
export API_PORT="${API_SERVER_PORT:-3004}"
lsof -iTCP:"$API_PORT" -sTCP:LISTEN -P -n 2>/dev/null | awk 'NR>1{print "PORT="ENVIRON["API_PORT"], "PID="$2}'
# 2. 进程启动时间
ps -p <PID> -o lstart=
# 3. Runtime worktree HEAD vs 目标 commit
git -C <runtime-worktree> log --oneline -1 # HEAD=
TARGET_COMMIT=<你预期的commit>
# 判断进程是否在 commit 之后启动：比较 commit 时间 vs 进程启动时间
# 4. 当前 PID 在最新日志中的行数
grep -c "<PID>" <最新日志文件路径> # LOG_EVIDENCE=
收集到的 7 个字段：
PORT=3004 ← 默认 API 端口（3003=前端），只取 LISTEN PID
PID=53507 ← 精确到监听进程（排除浏览器等客户端连接）
START_TIME=... ← 进程启动时间
HEAD=abc1234 ... ← runtime worktree HEAD
TARGET_COMMIT=f78c984 ← 你预期的 commit
PROCESS_AFTER_TARGET=yes/no ← 进程是否在 commit 之后启动
LOG_EVIDENCE=... ← 当前 PID 在最新日志中的行数
这 7 行没拿到之前，唯一允许说的话是"我还没查完"。
以下断言必须附带 preflight 输出，否则禁止说出：
为什么这是硬门禁：启动脚本会自动拉代码并编译。"没更新"本来就不太可能发生。在没有证据的情况下说"没更新" = 把自己的 bug 甩锅给operator。这不是懒，是推卸责任。
来源：operator多次纠正（2026-04-05 定为 P0），Maine Coon协助定位根因 + 方案审查。
每个阶段必须完成才能进入下一个。
Phase 1 — 根因调查（提出任何修复前必须完成）
对每个组件边界：记录进入的数据、记录输出的数据、验证状态传播
先跑一次收集"哪里断了"的证据，再分析，再深入那个组件
root-cause-tracing.md）Phase 2 — 模式分析
Phase 3 — 假设验证
Phase 4 — 实现修复
tdd skill）⚠️ 3+ 次修复都失败 = 架构问题
出现以下模式就停下来质疑架构，不要尝试第 4 次修复：
停下来和operator讨论是继续修还是重新设计。
存放位置：docs/bug-report/<bug-name>/bug-report.md
五件套是调查完成后的存档格式，不是入口。 入口是诊断胶囊（见下方「Bug 诊断胶囊」节）。
收到 bug / 看到失败
↓
涉及 runtime？→ 是 → Runtime Preflight Gate（三件套）
↓ 否 / 三件套完成
填诊断胶囊（8 栏工作模板）← 入口！
↓
Phase 1: 根因调查（胶囊驱动）
↓ 找到根因？
Phase 2: 模式分析（对照工作代码）
↓
Phase 3: 假设验证（最小变更，一次一个）
↓ 假设确认？
Phase 4: 先写失败测试 → 修复 → 验证
↓ 修复 3 次仍未解决？
停下来 → 质疑架构 → 找operator讨论
↓ 修复完成
整理五件套存档（从胶囊提炼）
| 阶段 | 关键动作 | 完成标准 |
|---|---|---|
| 1. 根因调查 | 读错误、复现、加诊断桩、追数据流 | 清楚知道是什么、为什么 |
| 2. 模式分析 | 找工作代码、完整对照 | 找出差异列表 |
| 3. 假设验证 | 写下假设、最小变更测试 | 假设确认或新假设 |
| 4. 实现修复 | 先写失败测试、单一修复、验证 | bug 已解决，测试通过 |
听到自己说以下任何一句 → 停下来，回到 Phase 1：
| 错误 | 正确做法 |
|---|---|
| 没有诊断胶囊就直接修 | 先填 8 栏诊断胶囊，再进 Phase 1 |
| 看到症状就提修复方案 | Phase 1 根因调查必须完成才能提方案 |
| 多组件系统直接猜原因 | 加诊断桩，收集每层边界的证据 |
| 修完直接 push，不写测试 | 先写失败测试复现 bug，再修，再验证 |
| 第 3 次修复还在叠加 | 停下来，质疑架构，找operator |
| 错误信息略读 | 完整读 stack trace，记录行号和错误码 |
tdd：debugging 是修复性的（bug 出现后）；TDD 是预防性的（写代码前）。交叉点：Phase 4 写失败测试时切换到 TDD 模式quality-gate：debugging 是找到并修复问题；quality-gate 是提交前确认一切正常Phase 1 开始时，用 8 栏诊断胶囊 结构化调查过程：
胶囊 8 栏：现象 / 证据 / 问题假设或根因 / 诊断策略 / 超时策略 / 预警策略 / 用户可见交互修正（可选） / 验收
胶囊是调查过程的工作模板，五件套是 bug report 的存档格式。 两者互补：先填胶囊驱动调查，再整理五件套存档。
以下参考材料已随 skill 合并归档（原 systematic-debugging/ 目录），可从 git 历史查阅：
root-cause-tracing.md — 从 call stack 深处向上追踪原始触发点的完整技术defense-in-depth.md — 找到根因后，在多层添加防御性校验condition-based-waiting.md — 用条件轮询替代任意 timeout右侧状态面板底部有「运行日志 → 查看日志」按钮：
packages/api/data/logs/api/ 并打开最新日志文件api.YYYY-MM-DD.SEQ.log（日轮转，14天保留）POST /api/workspace/navigate {"path":"packages/api/data/logs/api/","action":"reveal","worktreeId":"..."}修复完成并通过验证后 → 加载 quality-gate 做提交前验收