Back to Details

troubleshooting-regression

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Troubleshooting Regression

回归问题排查

Use this skill when the framework appears stale, stuck, or regressed and you need deterministic diagnosis plus fix verification.
当框架出现停滞、卡顿或回归问题，且你需要确定性诊断及修复验证时，可使用此Skill。

When to Use

使用场景

  • Claude debug sessions stall after spawning agents.
  • Hooks block expected actions unexpectedly.
  • Memory/search/token-saver enforcement appears inconsistent.
  • A regression needs a repeatable reproduction and validation run.
  • Claude调试会话在生成Agent后停滞。
  • Hooks意外阻止预期操作。
  • Memory/Search/Token-Saver的执行表现不一致。
  • 需要可重复复现并验证修复的回归问题。

Iron Law

铁则

Do not declare a regression fixed without:
  1. reproducible trigger prompt,
  2. trace evidence from 
    pnpm trace:query
    ,
  3. hook/tool evidence from debug logs,
  4. targeted test pass for touched scope.
在未满足以下条件前，不得宣称回归问题已修复：
  1. 可复现的触发提示词，
  2. 来自
    pnpm trace:query
    的追踪证据，
  3. 来自调试日志的Hook/工具证据，
  4. 针对受影响范围的定向测试通过。

Workflow

工作流

  1. Identify session and log source.
  2. Run trace query first (
    pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200
    ).
  3. Extract high-signal errors (excluding known MCP auth/startup noise).
  4. Map each error to owning hook/module.
  5. Patch minimal code path and add/update regression test.
  6. Run targeted checks (tests + lint/format on changed files).
  7. Re-run debug prompt and verify error class no longer reproduces.
  8. Record learnings/issues in memory.
  1. 确定会话及日志来源。
  2. 先运行追踪查询（
    pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200
    ）。
  3. 提取高信号错误（排除已知的MCP认证/启动噪音）。
  4. 将每个错误映射到对应的Hook/模块。
  5. 修补最小代码路径并添加/更新回归测试。
  6. 运行定向检查（针对变更文件的测试+代码检查/格式化）。
  7. 重新运行调试提示词，验证错误类型不再复现。
  8. 在Memory中记录经验/问题。

Evidence Model

证据模型

  • Source of truth: 
    C:\\Users\\<user>\\.claude\\debug\\*.txt
  • Trace source of truth: 
    pnpm trace:query
    output for the same incident window
  • Filter: ignore external MCP transport/auth noise; keep framework/runtime errors
  • Error classes:
    • routing/task lifecycle
    • memory/search/token-saver guardrails
    • hook contract/schema violations
    • workflow phase/idempotency failures
  • 可信来源：
    C:\\Users\\<user>\\.claude\\debug\\*.txt
  • 追踪可信来源：同一事件窗口的
    pnpm trace:query
    输出
  • 过滤规则：忽略外部MCP传输/认证噪音；保留框架/运行时错误
  • 错误类型：
    • 路由/任务生命周期
    • Memory/Search/Token-Saver防护机制
    • Hook契约/ schema违规
    • 工作流阶段/幂等性失败

Command Surface

命令集

Primary wrapper:
bash
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
Optional direct log analysis:
bash
node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "C:\\Users\\<user>\\.claude\\debug\\<session>.txt"
主包装器：
bash
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
可选直接日志分析：
bash
node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "C:\\Users\\<user>\\.claude\\debug\\<session>.txt"

Output Contract

输出约定

  • ok
    : boolean
  • logPath
    : analyzed log path
  • findings[]
    : normalized findings with severity and owner file hints
  • nextActions[]
    : concrete fix/validation actions
  • ok
    ：布尔值
  • logPath
    ：已分析的日志路径
  • findings[]
    ：标准化的排查结果，含严重程度及所属文件提示
  • nextActions[]
    ：具体的修复/验证操作

Related Artifacts

相关工件

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

Examples

示例

bash
undefined
bash
undefined

Analyze latest log

分析最新日志

node .claude/skills/troubleshooting-regression/scripts/main.cjs --mode quick
node .claude/skills/troubleshooting-regression/scripts/main.cjs --mode quick

Analyze specific log and fail when critical findings exist

分析特定日志，若存在严重问题则终止

node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "<path>" --strict
undefined
node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "<path>" --strict
undefined

Memory Protocol

Memory协议

Before starting:
bash
cat .claude/context/memory/learnings.md
After completing:
  • Regression pattern -> 
    .claude/context/memory/learnings.md
  • Open defect or risk -> 
    .claude/context/memory/issues.md
  • New enforcement decision -> 
    .claude/context/memory/decisions.md
ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.
开始前：
bash
cat .claude/context/memory/learnings.md
完成后：
  • 回归模式 -> 
    .claude/context/memory/learnings.md
  • 未解决缺陷或风险 -> 
    .claude/context/memory/issues.md
  • 新的执行决策 -> 
    .claude/context/memory/decisions.md
假设中断：你的上下文可能会重置。若未记录到Memory中，则视为未发生。