diagnose

name	diagnose
description	Investigate and diagnose problems using structured evidence gathering and hypothesis testing. Use whenever something is broken, failing, or behaving unexpectedly — build errors, test failures, runtime exceptions, deployment issues, or performance problems.
allowed-tools	Bash, Read, Glob, Grep, Task, WebSearch, mcp__context7__resolve-library-id, mcp__context7__query-docs
user-invocable	true

Diagnose

Systematically investigate a problem using evidence-based reasoning. This skill follows a structured investigation methodology to find root causes and propose solutions.

Arguments

• {problem} — Description of the problem to investigate (required)
• --quick — Fast diagnosis, skip deep analysis
• --logs — Include log analysis in investigation

Process

Phase 1: Problem Statement

Clarify the problem:

• What is the expected behavior?
• What is the actual behavior?
• When did it start? (commit, deployment, time)
• Is it reproducible? How?
• What's the impact? (severity, affected users)

Phase 2: Evidence Collection

Use an investigator approach to gather evidence systematically.

Source 1: Error Messages & Logs

# Recent git history
git log --oneline -20

# Search for related errors in codebase
grep -r "ERROR_CODE" src/

# If --logs flag, search log patterns
grep -rn "{error pattern}" logs/

Source 2: Code Analysis

# Find related code
grep -rn "{symptom keyword}" src/

# Check recent changes to affected area
git log -p --since="1 week ago" -- {affected paths}

# Find usages and dependencies
grep -rn "{function/class name}" src/

Source 3: Configuration

# Check appsettings
cat src/**/appsettings*.json | grep -i "{related config}"

# Check environment variables
grep -rn "GetEnvironmentVariable\|GetValue<" src/ | grep -i "{related}"

Source 4: Tests

# Find related tests
grep -rn "{feature}" tests/

# Check if tests are passing
dotnet test --filter "{test pattern}" --no-build

Source 5: External Context

• Search for similar issues in GitHub issues
• Search for related error messages online
• Check documentation for expected behavior
• Use context7 to look up library docs when the error involves a specific library (EF Core, WolverineFx, FluentValidation, Polly, NATS.Net, TanStack Query) — this often reveals known issues or correct usage patterns faster than web search

Phase 3: Hypothesis Generation

Based on evidence, generate hypotheses ranked by likelihood:

## Hypotheses

| # | Hypothesis | Likelihood | Evidence For | Evidence Against |
|---|------------|------------|--------------|------------------|
| H1 | {hypothesis} | High | {evidence} | {counter-evidence} |
| H2 | {hypothesis} | Medium | {evidence} | {counter-evidence} |
| H3 | {hypothesis} | Low | {evidence} | {counter-evidence} |

Phase 4: Hypothesis Testing

For each hypothesis (starting with highest likelihood):

1. Identify test — What would confirm/refute this hypothesis?
2. Execute test — Run the test (code inspection, running test, reproduction)
3. Record result — Did it confirm or refute?
4. Update likelihood — Adjust rankings based on result

### Testing H1: {hypothesis}

**Test:** {what we'll do to test}
**Result:** {CONFIRMED / REFUTED / INCONCLUSIVE}
**Evidence:** {what we found}
**New likelihood:** {Updated: High/Medium/Low}

Phase 5: Root Cause Analysis

Once a hypothesis is confirmed:

5 Whys Analysis:

1. Why did {symptom} happen? → {immediate cause}
2. Why did {immediate cause} happen? → {deeper cause}
3. Why did {deeper cause} happen? → {even deeper}
4. Why? → {root cause candidate}
5. Why? → {root cause}

Contributing Factors:

• {Factor 1}
• {Factor 2}

Phase 6: Solution Proposal

## Proposed Solutions

### Solution 1: {name} (Recommended)

**Approach:** {description}

**Changes Required:**
- {file}: {change description}
- {file}: {change description}

**Pros:**
- {advantage}

**Cons:**
- {disadvantage}

**Risk:** {Low/Medium/High}
**Effort:** {Small/Medium/Large}

---

### Solution 2: {name} (Alternative)

{same structure}

---

### Recommendation

{Which solution and why}

Phase 7: Prevention

## Prevention Measures

### Immediate
- [ ] {Quick fix or guard}

### Short-term
- [ ] {Test to add}
- [ ] {Validation to add}

### Long-term
- [ ] {Architecture improvement}
- [ ] {Process change}

Output Format

# Diagnosis Report: {Problem Title}

**Reported:** {date}
**Severity:** {Critical/High/Medium/Low}
**Status:** {Investigating/Root Cause Found/Solution Proposed}

---

## Problem Statement

{Clear description of the problem}

**Expected:** {expected behavior}
**Actual:** {actual behavior}
**Reproduction:** {steps to reproduce}

---

## Evidence Summary

| Source | Finding | Relevance |
|--------|---------|-----------|
| {source} | {finding} | {High/Medium/Low} |

---

## Investigation Timeline

1. {timestamp} — {action taken} → {result}
2. {timestamp} — {action taken} → {result}

---

## Root Cause

**Confirmed Cause:** {root cause description}

**5 Whys:**
{analysis}

**Contributing Factors:**
- {factor}

---

## Solutions

{Solution proposals from Phase 6}

---

## Prevention

{Prevention measures from Phase 7}

---

## Appendix: Raw Evidence

<details>
<summary>Evidence Details</summary>

{Detailed evidence collected}

</details>

Quick Mode (--quick)

For urgent issues, use abbreviated process:

1. Collect obvious evidence (2 min)
2. Form top hypothesis
3. Test immediately
4. Propose quick fix
5. Note: "Full diagnosis recommended after fix"

Guidelines

• Follow the evidence — don't jump to conclusions
• Document everything — future you will thank past you
• Consider multiple hypotheses — avoid confirmation bias
• Test hypotheses — don't assume, verify
• Think systematically — use the 5 Whys
• Propose prevention — fix the system, not just the symptom