Claude-prime diagnose

Think harder.

Process

Check conversation context and skip completed steps.

1. Understand the symptom

• Read the bug report, errors, logs, and surrounding code carefully
• Clarify reproduction steps, expected behavior, and environment when they are unclear
• Separate confirmed facts from working assumptions. List them explicitly:

  • Fact (confirmed):

    the server returns 200

  • Assumption (unconfirmed):

    the client receives the full HTML body Misidentifying an assumption as a fact is the most common source of wasted investigation.

2. Build hypotheses

• Form 2-4 plausible root-cause hypotheses that are mechanistically distinct — different failure layers (e.g., server render vs. client hydration vs. network layer), not variations of the same idea

• Rank them by likelihood

• For each hypothesis, state both sides:

  • Confirm if:

    [what observation would prove this is the cause]

  • Eliminate if:

    [what observation would rule this out]

  A hypothesis you can't falsify in both directions is too vague to test.

3. Choose the lightest evidence method

Start with the cheapest source of truth that can kill hypotheses:

• existing logs, traces, stack traces, metrics, and error output
• static code inspection around the suspected path
• config, environment, deploy, cache, queue, and permissions state that could explain the symptom
• targeted reproduction in the relevant environment

Only add new instrumentation when existing evidence is insufficient.

• If you need runtime probes, read

  diagnose/references/runtime-debugging.md

• Use

  #region agent log

  /

  #endregion

  markers for any instrumentation you add
• Tag each log point with the relevant

  hypothesisId

• Log only the minimum fields needed to discriminate between hypotheses; never log secrets, tokens, passwords, cookies, or full sensitive payloads
• If runtime probes require starting the local debug server, ask the user before launching it
• For browser/UI bugs, combine with the

  agent-browser

  skill when reproduction or inspection needs it

4. Gather evidence and iterate

• Use existing logs, traces, failing tests, or artifacts before asking for a fresh reproduction
• When reproduction is needed, ask the user to trigger the bug — tie each request to the hypothesis it tests
• Correlate each finding with the hypothesis it supports or eliminates; narrow based on evidence, not confidence
• If ambiguity remains, refine hypotheses and add narrower probes — but stop and report when another round is unlikely to produce new discriminating evidence

5. Report the diagnosis

Output structured diagnosis:

## Diagnosis: [Issue Title]

### Symptoms
- [What was observed]

### Evidence
- [Finding] — `file:line` or runtime source — hypothesis X
- ...

### Root Cause
[Confirmed or most likely cause, with evidence]

### Hypotheses Tested
| # | Hypothesis | Confirm if | Eliminate if | Result |
|---|-----------|-----------|-------------|--------|
| A | ... | [what observation would prove this] | [what observation would rule this out] | Confirmed/Eliminated/Inconclusive |

### Recommended Next Steps
- [What to do next — usually hand off to `/fix` with this diagnosis]

### Active Instrumentation
- [List files with `#region agent log` blocks still in place, or `None`]

Constraints

• NO fixing — investigation and diagnosis only. "Recommended Next Steps" hands off to

  /fix

  with the diagnosis; it does not prescribe specific parameter values, code snippets, or step-by-step implementation instructions.
• Evidence over assumptions — if the code looks wrong but runtime evidence says otherwise, trust the runtime
• If you add

  #region agent log

  blocks, leave them in place for

  /fix

  to verify the repair and call them out in the final report

Bug

<bug>$ARGUMENTS</bug>