# Diagnose

> Investigate unexpected behavior and mysterious bugs. Use when the cause of a problem is unknown and the user needs to understand WHY something is happening — symptoms like: sudden unexplained changes in metrics or behavior, works locally but not in staging/production, inconsistent or intermittent failures, correct code producing wrong results, operations succeeding but having no effect, environme…

- **Type:** Skill
- **Install:** `agentstack add skill-avibebuilder-claude-prime-diagnose`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [avibebuilder](https://agentstack.voostack.com/s/avibebuilder)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [avibebuilder](https://github.com/avibebuilder)
- **Source:** https://github.com/avibebuilder/claude-prime/tree/main/.claude/skills/diagnose
- **Website:** https://claudeprime.avibebuilder.com

## Install

```sh
agentstack add skill-avibebuilder-claude-prime-diagnose
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

$ARGUMENTS

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [avibebuilder](https://github.com/avibebuilder)
- **Source:** [avibebuilder/claude-prime](https://github.com/avibebuilder/claude-prime)
- **License:** MIT
- **Homepage:** https://claudeprime.avibebuilder.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-avibebuilder-claude-prime-diagnose
- Seller: https://agentstack.voostack.com/s/avibebuilder
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.