메뉴
系统化 bug 定位：根因调查 → 模式分析 → 假设验证 → 修复。 Use when: 遇到 bug、测试失败、unexpected behavior。 Not for: 新功能开发、重构、已知原因的简单修复。 Output: Bug report（5件套）+ 根因 + 修复（含回归测试）。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
约定图发现方法论：进一个 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 做提交前验收