differential-diagnosis

Differential Diagnosis Methodology

Purpose

Framework for reasoning about competing hypotheses when analyzing correlated failures. Use this when you observe patterns across multiple entities (interfaces, devices, time periods) and need to determine probable cause.

Core Principle

Say the reasoning out loud. Don't just conclude—show WHY.

Bad: "Transceiver batch defect likely" Good: "100% (5/5) XYL2302xx transceivers show issues, 0% (0/15) non-XYL2302xx. Correlation strength: STRONG. Batch defect most probable."

Correlation Strength Calculation

When entities share a characteristic (serial prefix, linecard, vendor, time window):

affected_in_group / total_in_group  vs  affected_outside / total_outside

Thresholds:

Example:

• 5/5 XYL2302xx transceivers show issues = 100%
• 0/15 other transceivers show issues = 0%
• Correlation: STRONG (100% vs 0%)

Always quantify: "5/5 affected" not "several affected"

Hypothesis Ranking

For any correlation finding, generate competing hypotheses and rank by probability.

Framework

1. List plausible causes (minimum 3)
2. For each, identify expected evidence - what WOULD and WOULD NOT exist
3. Compare against actual evidence
4. Eliminate contradicted hypotheses - show why they fail
5. Rank remainder by parsimony - fewer assumptions = higher probability

Output Format

correlation_analysis:
  primary_hypothesis: "Description"
  confidence: 0.92  # 0.0-1.0

  supporting_evidence:
    - "Quantified observation 1"
    - "Quantified observation 2"
    - "Reasoning chain that supports conclusion"

  rejected_alternatives:
    - hypothesis: "Alternative 1"
      why_rejected: "Specific evidence that contradicts it"
    - hypothesis: "Alternative 2"
      why_rejected: "Specific evidence that contradicts it"

  recommended_action: "Specific actionable step"

Confidence Scoring

Temporal Analysis

For intermittent/recurring issues, calculate:

temporal_metrics:
  rate: 0.58           # events per minute
  period_sec: 103      # average seconds between events (60/rate)
  first_event: "Sep 12 09:40:20"
  last_event: "Sep 12 09:57:37"
  trend: "sustained"   # sustained | was_worse | accelerating

Trend calculation:

expected_total = rate_per_min × total_uptime_minutes
actual_total = observed count from counters

if expected ≈ actual (within 20%): sustained
if expected << actual: was_worse (slowing down)  
if expected >> actual: accelerating (getting worse)

Parsimony Principle

Prefer explanations requiring fewer independent failures.

Example:

• Hypothesis A: "One bad transceiver batch" (1 cause → 5 failures)
• Hypothesis B: "5 independent fiber issues" (5 causes → 5 failures)

Hypothesis A is more parsimonious. Choose A unless B has strong specific evidence.

Fault Localization

Different symptoms localize to different components. Domain-specific agents define their own localization rules, but the pattern is:

Symptom → Localizes to → Rules out

The agent should explicitly state what the symptom pattern rules OUT, not just what it points to.

Anti-Patterns (Don't Do These)

1. Assertion without evidence: "Bad transceiver" without showing correlation
2. Vague quantification: "Several interfaces affected" instead of "5/8 (62%)"
3. Missing alternatives: Only one hypothesis considered
4. No elimination: Alternatives listed but not rejected with evidence
5. Confidence without calibration: 0.95 confidence with WEAK correlation

Integration

Agents load this skill and apply it when:

• Multiple entities show similar symptoms
• Pattern detection identifies groupings (batch, linecard, time window)
• Cross-device or cross-interface correlation exists

The agent's domain-specific system prompt defines:

• What symptoms mean in that domain
• Fault localization rules for that domain
• Relevant grouping characteristics (serial numbers, linecards, etc.)

This skill provides the reasoning framework. The agent provides domain expertise.