Diagnose — Forced Anti-Thrash Investigation

Stop this pattern: symptom appears → agent assumes code bug → edits accumulate → root cause turns out to be stale process, wrong config, old binary, cache, missing secret, or bad assumption.

Code-path defect is one hypothesis class, not the default class.

Process

1. Intake Normalization

Rewrite the report into structured form in a single pass:

Symptom:
Expected behavior:
Observed behavior:
Scope: [frontend | backend | cli/tooling | deployment | unknown]
Recent changes:
How to reproduce:
Known constraints:
What already tried:

Scope inference: Do not ask the user to specify scope. Infer from the symptom:

• Mentions preview server, browser, layout, CSS, Svelte, component → frontend
• Mentions API, crash loop, service, endpoint, database → backend
• Mentions command, binary, version, PATH, install → cli/tooling
• Mentions deploy, pm2, start script, container, secrets, CI → deployment
• Unclear → unknown (use general hypothesis set)

2. Symptom Confirmation

Before theorizing, reproduce.

First confirm the issue exists exactly as described.
Do not propose fixes yet.
Run the minimum commands needed to verify the symptom and capture exact evidence.
If the symptom cannot be reproduced, pivot immediately to
mismatch-between-report-and-reality.

This catches the "tool assumed broken but actually works" class. A quick verification saves an entire investigation session.

3. Hypothesis Matrix

Generate at least 5 hypotheses, one per class, using this exact schema:

## Hypothesis Matrix

| ID | Class | Hypothesis | Why plausible | Test | Cost | Result |
|----|-------|------------|---------------|------|------|--------|
| H1 | Environment | ... | ... | ... | Low | Pending |
| H2 | Toolchain | ... | ... | ... | Low | Pending |
| H3 | Config/State | ... | ... | ... | Low | Pending |
| H4 | Observability | ... | ... | ... | Low | Pending |
| H5 | Code | ... | ... | ... | Medium | Pending |

Hypothesis classes — always consider all five:

Environment / Process

• Stale dev server, wrong running process, wrong start script
• Missing env vars / secrets, pm2/systemd/container drift
• Port collision, stale compiled assets, wrong working directory

Toolchain / Dependency

• Outdated binary, wrong package version, lockfile drift
• Node/Python/.NET version mismatch, build cache corruption
• Packaging/discovery issue (setuptools, npm workspace hoisting)

Configuration / State

• Incorrect config value, feature flag mismatch, bad local state
• Cookie/session/cache issue, DB/data mismatch, migration not applied

Observability Gap

• Logs not checked, logs misleading/incomplete
• Wrong service inspected, missing reproduction detail

Code-Path Defect

• Actual logic bug, bad assumption in control flow
• Framework constraint (Svelte 5 rules, Tailwind interactions)
• Integration mismatch between components

4. Investigation Order

Test hypotheses in this priority:

1. Cheapest test first — a version check costs nothing, a code refactor costs everything
2. Highest information gain — a test that eliminates an entire class beats one that narrows within a class
3. Non-destructive — read/log/inspect before edit/restart
4. Read-only first pass — check process state, logs, versions, config before touching anything
5. Restart only after inspecting current state — understand what's running before replacing it

Critical rule for runtime/process issues: Inspect the official start path (start scripts, ecosystem config, systemd units) before recreating or replacing process entries. A classic failure mode: a process-manager restart silently drops secrets because the env was never reloaded from the vault.

Update the hypothesis matrix as evidence arrives. Mark each result: Confirmed, Ruled out, Inconclusive, Pending.

5. Edit Gate

Do not edit code until:
1. The symptom is confirmed via reproduction
2. At least one non-code hypothesis class has been tested
3. There is evidence that a code change is the most likely fix

If you are about to edit code and cannot articulate which hypothesis
you are testing, STOP. Return to the matrix.

This is the skill's core enforcement mechanism. The natural LLM tendency is to start editing immediately. Resist it.

6. Fix and Verify

After narrowing the cause:

1. Apply the minimal fix — smallest change that addresses the root cause
2. Rerun the reproduction command from step 2
3. Verify adjacent behavior (did the fix break something else?)
4. State confidence level and remaining unknowns

7. Capture Recurrence

If the root cause is durable and text-preventable, propose one or more of:

• CLAUDE.md correction — if this class of mistake is likely to recur in this project
• Hook idea — if a mechanical check would catch it (version check, process check)
• Test/verification addition — if a test would prevent regression
• Auto-memory entry — if it applies cross-project or is a new insight worth preserving (the workspace's persistent memory store: one-fact file + index line). Legacy global LESSONS.md/CORRECTIONS.md are closed curated archives (2026-08-05) — do not add entries there.

Only propose what's warranted. Not every bug needs a correction entry.

Output Schema

# Diagnosis Report

## 1. Symptom Confirmation
[Reproduction result — confirmed, not reproduced, or differs from report]

## 2. Hypothesis Matrix
[The table from step 3, updated with results]

## 3. Evidence Collected
[What was checked, what was found — chronological investigation log]

## 4. Narrowed Cause
[Root cause with confidence level and reasoning]

## 5. Fix Applied
[What changed and why this is the minimal fix]

## 6. Verification
[Reproduction rerun result + adjacent behavior check]

## 7. Remaining Uncertainty
[What's still unknown, what to watch for]

## 8. Prevention / Memory Capture
[Required. Propose one or more of: CLAUDE.md correction, hook idea, test/verification addition, auto-memory entry. If none apply, write exactly: "None warranted — one-off issue unlikely to recur."]

Scope-Specific Bias

When scope is inferred, bias the hypothesis generation toward likely causes for that domain. These are starting biases, not exclusive lists — always include all five classes.

Frontend

Bias toward: stale preview server, browser cache, Tailwind/Vite/Svelte build artifacts, wrapper/class interactions, hydration/runtime console errors, CSS specificity conflicts

Backend

Bias toward: wrong environment, service not restarted, config/env drift, migration/data state, wrong endpoint/version, connection pool exhaustion

CLI / Tooling

Bias toward: PATH/version mismatch, outdated binary, lockfile/install drift, local shell alias/wrapper issues, missing global vs local install

Deployment

Bias toward: start script mismatch, missing secrets, process manager drift, container/image mismatch, stale mounted config, CI vs manual deploy race conditions

Invocation

Quick:

/diagnose "API service crash loop after restart"

Structured:

/diagnose
symptom: new SidebarNav component broke page centering
expected: main content stays centered after adding the component
observed: content appears offset / layout wrong
recent_changes:
  - added SidebarNav component
  - adjusted wrapper classes
reproduction: start preview and open the affected page
environment_hints:
  - preview server may already be running

Anti-patterns

• Jumping to code edits before testing environment/config hypotheses
• Generating a hypothesis matrix but then ignoring it
• Testing expensive hypotheses before cheap ones
• Restarting/recreating processes without inspecting their current state first
• "Fixing" something without confirming the symptom exists
• Proposing corrections for one-off issues that won't recur
• Treating the matrix as a formality — if you're not updating it with results, you're not using it

Hook Interplay

This skill is NOT a hook. It needs reasoning, not automation. A hook can supplement it — for example, a session-start hook that dumps process state, versions, and recent git changes as ambient context. But the diagnosis flow belongs in the skill.

---

Origin: a Claude Code insights report (2026-04-16) identifying environmental/state debugging loops as the highest-friction pattern. Direct lessons from real debugging sessions: a service crash loop (process manager dropped secrets), a component change that appeared to break layout (stale preview server), a CLI-tool version mismatch, and a false-positive symptom that couldn't be reproduced.

</supporting_info>