回归故障排除Skill troubleshooting-regression

---

name: troubleshooting-regression description: 针对钩子/路由器/内存/搜索故障的回归故障排除工作流程，附带强制证据和修复验证 argument-hint: ‘[–prompt “…”] [–log-path <路径>] [–mode quick|full]’ verified: false lastVerifiedAt: 2026-02-19T05:29:09.098Z

故障排除回归

当框架出现陈旧、卡住或回归时，使用此技能进行确定性诊断和修复验证。

何时使用

• Claude 调试会话在生成代理后卡住。
• 钩子意外地阻止预期操作。
• 内存/搜索/令牌节省器强制执行似乎不一致。
• 需要可重复的回归再现和验证运行。

铁律

没有以下情况，不要声明回归已修复：

1. 可重复的触发提示，
2. 来自 pnpm trace:query 的跟踪证据，
3. 来自调试日志的钩子/工具证据，
4. 针对受影响范围的目标测试通过。

工作流程

1. 识别会话和日志源。
2. 首先运行跟踪查询（pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200）。
3. 提取高信号错误（排除已知的 MCP 认证/启动噪声）。
4. 将每个错误映射到所属的钩子/模块。
5. 修补最小代码路径并添加/更新回归测试。
6. 运行目标检查（测试 + 对更改文件的 lint/格式检查）。
7. 重新运行调试提示并验证错误类别不再重现。
8. 在内存中记录学习内容/问题。

证据模型

• 真相源：C:\Users\<用户>\.claude\debug\*.txt
• 跟踪真相源：同一事件窗口的 pnpm trace:query 输出
• 过滤器：忽略外部 MCP 传输/认证噪声；保留框架/运行时错误
• 错误类别：
  • 路由/任务生命周期
  • 内存/搜索/令牌节省器护栏
  • 钩子契约/模式违规
  • 工作流阶段/幂等性失败

命令界面

主要包装器：

node .claude/skills/troubleshooting-regression/scripts/main.cjs --prompt "search the codebase for any issues or bugs"
pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200

可选直接日志分析：

node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "C:\Users\<用户>\.claude\debug\<session>.txt"

输出契约

• ok: 布尔值
• logPath: 分析的日志路径
• findings[]: 带有严重性和所有者文件提示的标准化发现
• nextActions[]: 具体的修复/验证操作

相关工件

• 工作流：.claude/workflows/troubleshooting-regression-skill-workflow.md
• 工具：.claude/tools/troubleshooting-regression/troubleshooting-regression.cjs
• 命令：.claude/commands/troubleshooting-regression.md

示例

# 分析最新日志
node .claude/skills/troubleshooting-regression/scripts/main.cjs --mode quick

# 分析特定日志并在存在关键发现时失败
node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "<路径>" --strict

内存协议

开始前：

cat .claude/context/memory/learnings.md

完成后：

• 回归模式 -> .claude/context/memory/learnings.md
• 开放缺陷或风险 -> .claude/context/memory/issues.md
• 新的强制执行决策 -> .claude/context/memory/decisions.md

假设中断：您的上下文可能会重置。如果不在内存中，它就没有发生。