troubleshooting-regression

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:

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.

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.

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

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-8601> --limit 200

Optional direct log analysis:

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

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 "<path>" --strict

Iron Laws

1. ALWAYS collect evidence (logs, trace IDs, error messages) before making any configuration changes
2. NEVER modify hook or routing configuration without first reproducing the failure deterministically
3. ALWAYS validate the fix by running the full regression test suite after each change
4. NEVER mark a regression resolved until the exact failure scenario passes end-to-end
5. 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.