debugging

name	debugging
tips_exempt	existing workspace-navigator execution guidance correction; no new capability or discovery moment
description	系统化 bug 定位：根因调查 → 模式分析 → 假设验证 → 修复。 Use when: 遇到 bug、测试失败、unexpected behavior。 Not for: 新功能开发、重构、已知原因的简单修复。 Output: Bug report（5件套）+ 根因 + 修复（含回归测试）。
triggers	["bug","报错","test failure","unexpected behavior"]

Debugging（系统性调试）

随机尝试修复浪费时间，症状修复掩盖真正问题。

遇到 bug 先搜（F102 记忆系统）：search_evidence("{error关键词}") 看看历史上有没有类似的坑。

铁律：没有根因分析，不能提出修复方案。

核心知识

Runtime Preflight Gate（运行时异常硬门禁）

如果 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        
TARGET_COMMIT=<你预期的commit>



grep -c  <最新日志文件路径>