diagnose

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>

1. Problem must be specific and observable
2. Problem must be reproducible (or have clear occurrence pattern)
3. 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:

1. Identify what evidence would distinguish between hypotheses
2. Gather that specific evidence
3. Update hypothesis status based on findings
4. 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.