| name | diagnose |
| description | Investigate why something is broken and identify the root cause through competing hypotheses and evidence — diagnoses only, never proposes fixes. Use before attempting a fix, when the cause isn't obvious. |
| argument-hint | <problem or symptom> |
Diagnose
You are an expert at identifying WHY problems occur through structured investigation. You diagnose root causes; you do NOT propose solutions. Understanding the problem fully before jumping to fixes prevents wasted effort on symptoms.
You have the skills to diagnose any problem. Proceed with confidence.
Interactive vs. delegated. This skill is you-drive, in-context investigation. For a delegated deep dive (a self-contained sub-agent that gathers evidence and reports back), dispatch the debugger agent (decaf-quality) instead — same diagnosis discipline, different control flow.
<scope_boundary>
This skill identifies ROOT CAUSES, not solutions.
- Output: "The root cause is [observable condition]"
- NOT output: "The fix is to add [solution]"
Solutions are a downstream concern. Your job is accurate diagnosis.
</scope_boundary>
When to Use
Use this for problems that need investigation:
- User reports "X happens when they do Y"
- Component A fails under condition B
- System exhibits unexpected behavior
- Bug needs investigation before fixing
- Error occurs intermittently without obvious cause
NOT for:
- Choosing between known solutions (use /decaf-plan:challenge-decision)
- Problems where the cause is already known (just fix it)
- Feature requests (not a problem to analyze)
The Problem/Solution Boundary
Root causes must be framed as conditions that exist, not as absences of solutions.
| WRONG (Absence) | CORRECT (Condition) |
|---|
| "We don't have validation" | "User input reaches processing without sanitization" |
| "Missing retry logic" | "Failed requests terminate immediately without retry" |
| "No rate limiting" | "The API accepts unbounded requests per client" |
| "Lack of monitoring" | "Component failures propagate silently until impact" |
The correct framing describes observable reality and leaves multiple solution paths open. The wrong framing presupposes a specific solution.
Workflow
Phase 1: Gate
Validate input and establish a single testable problem.
<gate_requirements>
- Problem must be specific and observable
- Problem must be reproducible (or have clear occurrence pattern)
- Problem must be singular (split compound problems)
</gate_requirements>
Gate Check:
| Criterion | Status | Notes |
|---|
| Specific? | [YES/NO] | Can you describe exact symptom? |
| Observable? | [YES/NO] | Can you see it happen? |
| Singular? | [YES/NO] | One problem, not multiple? |
If any criterion is NO, clarify with user before proceeding.
Output: Single problem statement
PROBLEM: [Specific observable symptom]
TRIGGER: [Conditions under which it occurs]
EXPECTED: [What should happen instead]
Phase 2: Hypothesize
Generate 2-4 distinct candidate explanations.
<hypothesis_requirements>
- Minimum 2 hypotheses (prevents tunnel vision)
- Maximum 4 hypotheses (prevents analysis paralysis)
- Each must differ in MECHANISM or LOCATION, not just phrasing
- Frame as conditions, not absences
</hypothesis_requirements>
Why multiple hypotheses matter:
Investigation with only one hypothesis produces confirmation bias. You find supporting evidence whether or not the hypothesis is correct because you're only looking for evidence that supports it.
Output:
| ID | Hypothesis | Mechanism | Location |
|---|
| H1 | Session token expires during request processing | Token lifetime shorter than request duration | AuthMiddleware |
| H2 | Mobile browser doesn't persist cookies correctly | Cookie storage not surviving app switch | Client-side |
| H3 | Load balancer routes to different server mid-session | Session affinity not configured | Infrastructure |
Phase 3: Investigate
Iterative evidence gathering. Maximum 5 iterations.
<investigation_protocol>
For each iteration:
- Identify what evidence would distinguish between hypotheses
- Gather that specific evidence
- Update hypothesis status based on findings
- Determine if another iteration is needed
</investigation_protocol>
Investigation Log:
ITERATION 1:
Target: Distinguish H1 (token expiry) from H2 (cookie persistence)
Action: Examine token lifetime configuration and cookie settings
Evidence: Token lifetime = 3600s, cookie max-age = 3600s
Finding: Token lifetime matches cookie lifetime, rules out simple mismatch
H1 status: POSSIBLE (need to check actual expiry timing)
H2 status: POSSIBLE (need to check mobile-specific behavior)
ITERATION 2:
Target: Check if mobile requests show different cookie behavior
Action: Search for mobile user-agent handling, cookie logging
Evidence: Found header inspection in AuthMiddleware line 142
Finding: [specific finding]
...
Iteration Exit Conditions:
- HIGH confidence achieved (see Phase 4)
- Maximum iterations (5) reached
- All hypotheses eliminated (need new hypotheses)
Phase 4: Formulate
Synthesize findings into validated root cause.
Confidence Assessment:
Do not ask "how confident are you?" — LLMs have no calibrated introspective access to certainty. Instead, answer four factual questions:
| Question | Criterion | Answer |
|---|
| Evidence | Can you cite specific code/config/docs supporting the cause? | [YES/PARTIAL/NO] |
| Alternatives | Did you examine at least one alternative hypothesis? | [YES/PARTIAL/NO] |
| Explanation | Does the root cause fully explain the symptom? | [YES/PARTIAL/NO] |
| Framing | Is root cause a positive condition (not absence)? | [YES/NO] |
Scoring:
- YES = 1 point, PARTIAL = 0.5 points, NO = 0 points
- Question 4 (Framing) has no partial credit
| Score | Confidence | Action |
|---|
| 4 | HIGH | Ready to proceed |
| 3-3.5 | MEDIUM | Document uncertainty, may proceed |
| 2-2.5 | LOW | More investigation needed |
| <2 | INSUFFICIENT | Cannot proceed |
Important: You can only truly confirm a root cause after implementing a fix and observing the symptom disappears. Before that, you're working with hypotheses. The goal is "sufficient confidence to proceed," not certainty.
Phase 5: Output
Structured report for downstream consumption.
## Root Cause Analysis Report
### Problem Statement
[From Phase 1]
### Root Cause
[Single sentence describing the observable condition causing the problem]
### Evidence
| Evidence | Source | Supports |
|----------|--------|----------|
| [Specific finding] | [file:line or observation] | Root cause |
| [Specific finding] | [file:line or observation] | Rules out H2 |
### Confidence Assessment
| Criterion | Score | Notes |
|-----------|-------|-------|
| Evidence | [1/0.5/0] | [Citation] |
| Alternatives | [1/0.5/0] | [Which examined] |
| Explanation | [1/0.5/0] | [How it explains symptom] |
| Framing | [1/0] | [Condition, not absence] |
| **Total** | [X/4] | [HIGH/MEDIUM/LOW] |
### Hypotheses Evaluated
| ID | Hypothesis | Final Status | Key Evidence |
|----|------------|--------------|--------------|
| H1 | [Description] | CONFIRMED | [Evidence] |
| H2 | [Description] | RULED OUT | [Evidence] |
### Investigation Summary
[Brief narrative of the investigation path]
### Remaining Uncertainty
[What would need to be true for this diagnosis to be wrong]
Anti-Patterns
<anti_pattern_stop>
If you catch yourself doing any of these, STOP and correct immediately.
</anti_pattern_stop>
1. Jumping to solutions
WRONG: "The root cause is missing validation, so we should add input checking."
RIGHT: "The root cause is that user input reaches processing without sanitization."
2. Single hypothesis investigation
WRONG: "I think it's X, let me find evidence for X."
RIGHT: "I have hypotheses X, Y, Z. What evidence distinguishes them?"
3. Absence framing
WRONG: "The root cause is lack of error handling."
RIGHT: "The root cause is that exceptions propagate to the UI unformatted."
4. Claiming certainty
WRONG: "I am 100% certain the root cause is X."
RIGHT: "Confidence is HIGH (4/4). Root cause is X. Would be wrong if [condition]."
5. Stopping too early
WRONG: "I found something that could cause this, must be the root cause."
RIGHT: "I found a candidate. Does it fully explain the symptom? Did I check alternatives?"
Example
Input:
Users report their session expires immediately after login on mobile devices, but works fine on desktop.
Phase 1 Output:
PROBLEM: Session expires immediately after login on mobile
TRIGGER: Login from mobile browser
EXPECTED: Session persists like desktop (typically 1 hour)
Phase 2 Output:
| ID | Hypothesis | Mechanism | Location |
|---|
| H1 | Mobile browser rejects cookies due to SameSite policy | Cookie policy incompatible with mobile | Cookie configuration |
| H2 | Mobile app switching triggers session invalidation | Background/foreground transition clears session | Client storage |
| H3 | Token expiry calculated differently for mobile user agents | Server-side mobile detection affects token lifetime | AuthService |
Phase 3 Output:
ITERATION 1:
Target: Check cookie configuration for SameSite policy
Action: Read auth cookie settings in startup configuration
Evidence: Cookie set with SameSite=Strict, Secure=true
Finding: SameSite=Strict prevents cookie being sent on cross-site navigation
H1 status: LIKELY (SameSite=Strict is problematic for mobile OAuth flows)
H2 status: POSSIBLE (still need to verify)
H3 status: POSSIBLE (still need to verify)
ITERATION 2:
Target: Verify mobile OAuth flow involves cross-site navigation
Action: Trace OAuth redirect flow for mobile login
Evidence: Mobile login redirects to OAuth provider, then back to app
Finding: Return redirect is cross-site, SameSite=Strict blocks cookie
H1 status: CONFIRMED
H2, H3: No longer primary suspects
Phase 5 Output:
## Root Cause Analysis Report
### Problem Statement
Session expires immediately after login on mobile devices, but works fine on desktop.
### Root Cause
The session cookie is configured with SameSite=Strict, which prevents the browser from sending the cookie on the OAuth callback redirect (cross-site navigation), causing the session to appear expired.
### Evidence
| Evidence | Source | Supports |
|----------|--------|----------|
| Cookie config: SameSite=Strict | Startup.cs:142 | Root cause |
| OAuth flow requires cross-site redirect | AuthController.cs:89 | Explains mobile-specific failure |
| Desktop login uses same-site form post | LoginController.cs:34 | Explains desktop success |
### Confidence Assessment
| Criterion | Score | Notes |
|-----------|-------|-------|
| Evidence | 1 | Cited Startup.cs:142, AuthController.cs:89 |
| Alternatives | 1 | Examined H2, H3 |
| Explanation | 1 | Fully explains mobile-only failure |
| Framing | 1 | Condition: "cookie blocked on cross-site" |
| **Total** | 4/4 | HIGH |
### Hypotheses Evaluated
| ID | Hypothesis | Final Status | Key Evidence |
|----|------------|--------------|--------------|
| H1 | SameSite policy blocks cookie | CONFIRMED | SameSite=Strict in config |
| H2 | App switching clears session | RULED OUT | Session never established |
| H3 | Mobile-specific token expiry | RULED OUT | Same token logic for all |
### Remaining Uncertainty
Would be wrong if: Mobile browsers have additional cookie handling we haven't discovered, or if there's a caching layer returning stale responses.
