Writing: read docs/skills/shared/writing-rule.md before you write a durable artifact.

/debug — Structured Debug Methodology

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 a deploy + a CEO approval + the user's patience. This skill enforces the discipline that prevents the loop:

1. Capture the symptom precisely — the exact URL, the exact response, the 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 ordered by probability, each with an explicit evidence test.
4. Gather evidence first, fix second — never ship a fix without a verification step that would have caught the wrong hypothesis.
5. Verify the fix against the original evidence — re-run the symptom check, not just the unit tests.

The cost of one extra curl, one extra Read, one extra "what does the server actually return?" — is one minute. The cost of one wrong fix that ships, deploys, blocks the user, and then has to be diagnosed again is hours.

When to invoke

Trigger this skill when any of the following is true:

• A previous fix attempt didn't resolve the symptom
• The symptom involves multiple layers (CDN, framework, backend, auth, network)
• Pattern-matching on the symptom produces more than one plausible cause
• The CEO has had to point out the bug exists more than once

If the cause is genuinely obvious (typo in a string, off-by-one in a loop), don't invoke this — just fix it. The skill is for the cases where you're tempted to guess.

Process

Step 1 — Capture the symptom

Write down, in this exact shape:

URL / endpoint:    <exact URL or command>
Action:            <what the user did>
Expected:          <what should have happened>
Observed:          <what actually happened>
Repro recipe:      <minimal steps that reproduce>
Surface evidence:  <screenshot URL, console output, response headers, logs>

If any field is "I'm not sure" — STOP and gather it before going further. Hypotheses built on a fuzzy symptom are guesses dressed up.

The minimum surface-evidence bar is stack-specific — see the appendix matching the bug's stack at the bottom of this skill (Web, Desktop). If your stack isn't listed, fall back to the general principle: capture what the system actually does at the moment of failure, not what it should do.

Step 2 — Map the architecture

Before forming hypotheses, read the relevant files. Don't reason about what the code probably does; check.

The architecture-surface table is stack-specific — see the appendix at the bottom matching the bug's context. The general rule is: walk every layer the failing operation touches, from the user input down to the persistence/external boundary, and read the file that handles each layer's responsibility.

Do not skip this step. This is where the actual bug usually lives. Most "tricky" bugs are tricky because the agent reasoned about an imagined architecture instead of reading the real one.

Step 3 — Hypothesis ladder

List 3–5 candidate causes, ordered by probability. For each, write the specific evidence that would prove or disprove it.

Format:

H1 (most likely):  <one-sentence cause>
   Evidence to confirm:    <command or observation that proves it>
   Evidence to refute:     <command or observation that proves it isn't this>

H2:  <one-sentence cause>
   Evidence to confirm:    ...
   Evidence to refute:     ...

H3:  ...

If you can't write a confirm-or-refute test for a hypothesis, it's not a hypothesis — it's a vibe. Replace it with one you can test, or drop it.

Common anti-pattern: "It might be a cache issue" — too vague. Replace with: "Browser has a cached 301 redirect for /auth/callback → /auth/callback/ from a previous deploy state. Confirm by reproing in incognito; refute if the symptom persists in incognito."

Step 4 — Gather evidence

Run the confirm test for H1 first. If it confirms → go to step 5. If it refutes → run the refute test, then move to H2.

The evidence-tests cookbook is stack-specific — see the appendix at the bottom matching the bug's context (Web, Desktop). Each table maps common hypothesis classes to the specific command or observation that confirms or refutes them.

Critical: the evidence test must be specific enough that "the test passed" actually rules out the hypothesis. "It looked right when I tested" doesn't count.

Step 5 — Implement the fix

Only after step 4 confirms a hypothesis. The fix should:

• Target the verified mechanism, not adjacent code that "looks suspicious"
• Be the smallest change that addresses the confirmed root cause
• NOT bundle "while I'm here" improvements (those are separate PRs)

If you're tempted to fix two things in the same PR because "they're related" — split. The wrong-diagnosis cost is N times higher when multiple changes are in flight.

Step 6 — Verify the fix against the original evidence

Re-run the same evidence command you used in step 4. If the original test was curl -I https://staging.x.com/auth/callback/, run that exact command again. Confirm:

• The status code changed in the expected direction
• The expected content is now served
• No new error appears in the chain

Unit tests passing is necessary but not sufficient — they verify code correctness, not feature correctness. A fix that passes tests but doesn't change the curl output didn't actually fix anything.

Step 7 — Watch for compounding issues

After a fix lands, the next symptom often hides a second-order bug. Don't declare victory until:

• The user confirms the original repro recipe now works end-to-end
• No new error appears in browser DevTools / server logs
• The fix has been tested in two distinct contexts (different machine, different account, different browser) — the same-session cache can mask both successes AND failures

If the user reports a new symptom right after your fix, do not treat it as a separate bug. It's almost always a compounding issue from the same root cause or your fix's side effect. Re-enter step 1 with the new symptom.

Output shape

A debug session run through this skill produces a single concise report:

DEBUG REPORT — <symptom summary> @ <date>

## Symptom
<filled in from step 1>

## Architecture surface
<bullet list of layers traversed in step 2 — file paths only, no narrative>

## Hypothesis ladder
H1 (chosen): <hypothesis> — confirmed by <evidence>
H2: <hypothesis> — refuted by <evidence>
H3: <hypothesis> — not tested (refuted by H1 confirmation)

## Fix
<file path>:<line>: <one-line summary of the change>

## Verification
<command run, before-output, after-output>

## Open follow-ups
<anything noticed that's NOT this bug but should be tracked>

Keep it under 30 lines. The discipline matters more than the documentation.

Anti-patterns this skill prevents

Relationship to other skills

When NOT to use this skill

• Simple bugs: typos, missing imports, obvious off-by-ones. The methodology overhead exceeds the gain.
• Greenfield exploration: you're learning the codebase, not debugging a regression.
• Architectural decisions: use /decide and write an AgDR; debugging is for "it doesn't work", not "which approach should we take".
• Performance investigation: similar discipline, but the toolkit is different (profiles, traces, flamegraphs). A separate /perf-debug skill could be filed if the gap matters.

Stack appendices

Each appendix carries the stack-specific surface-evidence requirements (step 1), architecture-surface map (step 2), and evidence-tests cookbook (step 4). The body of the skill stays methodology-only so it doesn't bloat as more stacks land.

Web appendix

Minimum surface evidence (step 1). Don't proceed without these:

• curl -I of the failing URL — response status + Location header
• Browser DevTools Network tab redirect chain — every status code and Location header from the user action to the visible failure
• Browser DevTools Console — any errors, including the stack trace
• The exact URL in the address bar at the moment of failure (often differs from what the user typed — note both)

Capture that evidence with a browser-automation MCP server (Playwright MCP or equivalent) rather than an ad-hoc headless-browser CLI invocation. Prefer an accessibility-tree snapshot over a screenshot when the hypothesis is about what the page says — a snapshot returns rendered text and roles, and it does not depend on animation timing. If you take a screenshot, wait until the page settles: a chart's draw-in animation captured at frame 0 renders empty, and that frame has already produced at least one confident, wrong root-cause finding.

Architecture-surface map (step 2). Read the file at every layer the request touches:

Evidence-tests cookbook (step 4).

Desktop appendix

Covers Electron / Tauri (web tech in a native shell) and native (Swift/Cocoa, .NET/Win32, GTK/Qt). For Electron and Tauri, the renderer process is essentially a web app — use the Web appendix for renderer-side bugs and this appendix for everything that crosses the native boundary.

Minimum surface evidence (step 1). Don't proceed without these:

• The exact reproduce sequence (which window, which menu item, which IPC call)
• Crash log if the app crashed (Console.app → Crash Reports on macOS, Event Viewer → Application on Windows, journalctl --user on Linux)
• App's own log file — most desktop apps log to a known path (~/Library/Logs/<App> on macOS, %APPDATA%\<App>\logs on Windows, ~/.local/state/<App>/ or stdout on Linux)
• Build/version info — <App>.app/Contents/Info.plist (macOS), <App>.exe properties (Windows), so you know what code is actually running
• For sandbox / permission issues: the entitlements (macOS: codesign -d --entitlements - <App>.app) or manifest capabilities (Windows AppX)

Architecture-surface map (step 2). Read the file at every layer the failing operation touches:

Evidence-tests cookbook (step 4).

Notes for skill maintainers

The methodology body is portable across stacks. The appendices are where stack-specific knowledge accumulates.

When to add a new appendix:

• A debug session in a new stack class (mobile, backend service, CLI tool, data pipeline) produces a useful evidence-tests pattern
• The user reports the existing appendices don't cover their stack and the gap is concrete

When updating an existing appendix:

• New evidence-test pattern proven useful in a real session — append to the cookbook table and mention the originating session in the commit message
• A row points at deprecated tooling — replace with the current best tool, don't keep both

Don't add an appendix until you have a real session's worth of patterns to seed it. A speculative "Mobile" appendix with three half-formed rows is worse than no Mobile appendix.

Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.