Summary

Adds the /debug skill at .claude/skills/debug/SKILL.md. Closes #141.

A methodology skill that enforces five disciplines on debug sessions:

1. Capture the symptom precisely (exact URL, exact response, exact step)
2. Read the architecture before guessing — map every layer the failing operation touches, file by file
3. Form a hypothesis ladder — 3–5 candidate causes, each with an explicit evidence test that confirms or refutes it
4. Gather evidence first, fix second
5. Verify the fix against the original symptom evidence — re-run the same curl / browser repro from step 4. Unit tests verify code correctness, not feature correctness.

Stack appendices (Web + Desktop) carry the stack-specific bits — surface-evidence requirements (step 1), architecture-surface maps (step 2), and evidence-tests cookbooks (step 4). The methodology body stays portable across stacks; appendices are where stack-specific knowledge accumulates over time.

Web appendix covers browser routing, framework configs (Next/Nuxt/Vite), SPA-fallback layers, CDN, origin, the shared API client, backend handlers, and auth providers.

Desktop appendix covers Electron / Tauri / native-shell concerns: app entry points, IPC bridges, native modules, auto-updater, sandbox / entitlements, code signing, crash reports.

Includes a "When NOT to use" section so the methodology overhead doesn't sandbag simple bugs (typos, off-by-ones, greenfield exploration), and a maintainer note ("don't add an appendix until you have a real session's worth of patterns to seed it") so we don't ship speculative half-finished tables.

Why this skill exists

A real OAuth debug session in a managed project saw three sequential fixes chase adjacent symptoms because each was hypothesis-then-fix without evidence in between. Each cycle costs deploys + approvals + user patience. This skill is the "never do that again" guardrail — and the methodology is generic enough that any stack benefits.

Testing

1. Markdown lint — single file, standard markdown; the markdown-lint workflow on .github/workflows/markdownlint.yml should pass
2. Lychee link-check — every link is either an in-repo relative path (no network roundtrip) or an external https:// link to commonly-stable resources; Link Check workflow should pass
3. No new hooks / no new scripts — pure skill addition, no shellcheck exposure
4. Skill discovery — Claude Code will pick up the new skill at runtime; no settings.json change required (skills are auto-discovered from .claude/skills/<name>/SKILL.md)

Per the apexyard release-cut model, this targets dev. After merge, the next release tag picks this up and adopters get the skill via /update.

Closes #141

Glossary