User Story

As an agent driving work in a Claude Code session, I want a structured debug methodology I can invoke when a bug resists naïve fixes, so that I stop the hypothesis-then-fix-without-evidence loop and resolve issues with one verified change instead of three guesses.

Motivation

Most "stuck" debug sessions look the same: pattern-match on the symptom, propose a fix, ship it, find a different symptom, repeat. Each cycle costs deploys, approvals, user patience. A real session in a managed project saw three sequential fixes chase adjacent symptoms because each was hypothesis-then-fix without evidence in between — that's the recurring failure mode this skill is designed to prevent.

The proposed /debug skill enforces five disciplines:

1. Capture the symptom precisely — exact URL, exact response, exact step that fails
2. Read the architecture before guessing — map every layer the request touches
3. Form a hypothesis ladder — 3–5 candidate causes, each with an explicit evidence test
4. Gather evidence first, fix second — never ship a fix without a verification step
5. Verify the fix against the original evidence — re-run the symptom check, not just unit tests

Acceptance Criteria

• New skill at .claude/skills/debug/SKILL.md with stack-agnostic methodology body
• Stack appendices for Web (browser routing, CDN, framework configs, auth, fetch wrapper) and Desktop (Electron / Tauri / native — IPC, sandbox, code signing, native modules)
• Each appendix has three sub-sections: minimum surface evidence (step 1), architecture-surface map (step 2), and evidence-tests cookbook (step 4)
• "When NOT to use" guidance so the methodology overhead doesn't sandbag simple bugs
• Anti-patterns table catalogues the failure modes (hypothesis-then-fix, pattern-match on URL shape, parallel fixes, declaring victory on unit-test pass, treating compounding symptoms as separate bugs)
• Maintainer notes: when to add a new appendix, when to update one (don't ship speculative half-finished tables)

Design Notes

• The body is portable across stacks; the appendices are where stack-specific knowledge accumulates
• Triggers: explicitly invokable via /debug; the description-line auto-trigger fires when a previous fix attempt didn't resolve the symptom, the symptom involves multiple layers, or pattern-matching produces more than one plausible cause
• Methodology output is a single concise report (~30 lines) — discipline matters more than the documentation
• No new hooks, no new agents — pure skill addition

Out of Scope

• Performance debugging (different toolkit — profiles, traces, flamegraphs). Could be a separate /perf-debug skill if the gap matters
• Mobile / Backend-service / CLI / Data-pipeline appendices — add only when a real session in that stack class produces a useful evidence-tests pattern. Speculative appendices ship half-formed and worse than no appendix.

Effort Estimate

Small. One markdown file, no code changes.