oimiragieo 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 <traceId> --compact --since <ISO-8601> --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\\<user>\\.claude\\debug\\*.txt - Trace source of truth:
pnpm trace:queryoutput 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: booleanlogPath: analyzed log pathfindings[]: normalized findings with severity and owner file hintsnextActions[]: 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
- 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.