Troubleshooting Regression

Use this skill when the framework appears stale, stuck, or regressed and you need deterministic diagnosis plus fix verification.

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.

Iron Law

Do not declare a regression fixed without:

reproducible trigger prompt,

trace evidence from

pnpm trace:query

,

hook/tool evidence from debug logs,

targeted test pass for touched scope.

Workflow

Identify session and log source.

Run trace query first (

pnpm trace:query --trace-id --compact --since --limit 200

).

Extract high-signal errors (excluding known MCP auth/startup noise).

Map each error to owning hook/module.

Patch minimal code path and add/update regression test.

Run targeted checks (tests + lint/format on changed files).

Re-run debug prompt and verify error class no longer reproduces.

Record learnings/issues in memory.

Evidence Model

Source of truth:

C:\Users\\.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

Command Surface

Primary wrapper:

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-860

1

>

--limit

200

Optional direct log analysis:

node

.claude/skills/troubleshooting-regression/scripts/main.cjs --log-path

"C:

\

Users

\

\

.claude

\

debug

\

.txt"

Output Contract

ok

boolean

logPath

analyzed log path

findings[]

normalized findings with severity and owner file hints

nextActions[]

concrete fix/validation actions Related Artifacts Workflow: .claude/workflows/troubleshooting-regression-skill-workflow.md Tool: .claude/tools/troubleshooting-regression/troubleshooting-regression.cjs Command: .claude/commands/troubleshooting-regression.md Examples

Analyze latest log

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 "" --strict Iron Laws ALWAYS collect evidence (logs, trace IDs, error messages) before making any configuration changes NEVER modify hook or routing configuration without first reproducing the failure deterministically ALWAYS validate the fix by running the full regression test suite after each change NEVER mark a regression resolved until the exact failure scenario passes end-to-end ALWAYS document the root cause, fix, and validation evidence in issues.md for future reference Anti-Patterns Anti-Pattern Why It Fails Correct Approach Making changes without reproducing failure Can't verify the change fixed the right thing Reproduce deterministically first, then fix Fixing symptoms without root cause analysis Problem recurs under different conditions Use 5 Whys to trace to the root cause Skipping regression suite after fix Fix may break other functionality Run full test suite after every change Undocumented fixes Same regression returns in future sessions Record root cause, fix, and validation in issues.md Resolving without end-to-end validation Integration issues are missed Validate the exact failure path end-to-end Memory Protocol Before starting: 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.