troubleshooting-regression

name	troubleshooting-regression
description	Regression troubleshooting workflow for hook/router/memory/search failures with enforced evidence and fix validation
argument-hint	[--prompt "..."] [--log-path <path>] [--mode quick|full]
verified	true
lastVerifiedAt	"2026-02-22T00:00:00.000Z"
version	1.0.0
tools	["Read","Write","Edit","Bash","Glob","Grep"]
source	builtin
trust_score	100
provenance_sha	b44d6767fd4adf12

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