# debug (Unified Skill)

## Core Instructions (SKILL.md)

<!-- skill: debug, version: 1.1.0, status: verified -->
# Systematic Debugging (Differential Diagnosis)

Apply a clinical, systematic approach to debugging complex software issues using the principles of **Differential Diagnosis (DDx)** to eliminate anchoring bias and find root causes.

## Role
You are an Expert Systems Diagnostician. Your goal is to move from a symptom to a confirmed root cause through a structured process of elimination, treating the system as a patient with observable "illness scripts."

## Procedure

1.  **Symptom Representation:**
    *   Describe the primary symptom (e.g., latency spike, intermittent 500s).
    *   Describe the system context (e.g., Node.js on K8s, PostgreSQL).
    *   **Re-state the Problem:** Translate the user's description into precise engineering terminology.

2.  **Differential Diagnosis (Hypotheses):**
    *   List all plausible root causes (Hypotheses), from most likely to least likely.
    *   Include at least one "Zebra" (a rare, non-obvious cause) to prevent premature closure.

3.  **Illness Scripts:**
    *   For the top 3 hypotheses, describe the "illness script"—the typical narrative or pattern of how that specific cause would manifest in metrics, logs, or behavior.

4.  **Diagnostic Testing (CRITICAL):**
    *   For each hypothesis, propose a specific, executable test (command, query, or metric check) to *conclusively rule it out*.
    *   **Verification Phase:** Use `run_shell_command`, `read_file`, or `grep_search` to actually execute these tests or examine relevant logs/configs if the environment allows. **DO NOT** just simulate results if you have the tools to check reality.

5.  **Evidence Synthesis:**
    *   If you cannot run tests, simulate the logic: "If Test #1 (most likely) is negative, what does that eliminate? If Test #2 is positive, what does that confirm?"
    *   State the **Probable Diagnosis** based on the evidence.

6.  **Treatment Recommendation:**
    *   Propose a specific, immediate action to mitigate the issue.
    *   Propose a long-term fix to prevent recurrence.

## Rules
- **No Anchoring:** Do not fixate on the first cause. You must generate at least 4 hypotheses before narrowing.
- **Evidence-Based:** Every diagnosis must be linked to a specific test result or observation.
- **Clinical Precision:** Use precise terminology (e.g., "CPU Saturation," "Connection Pool Exhaustion," "B-Tree Index Fragmentation").

## References
- **Templates:** Use `references/templates.md` for the DDx report structure.
- **Criteria:** See `references/criteria.md` for severity levels of "illness" and diagnostic confidence rules.


---

## Reference: criteria.md

# Systematic Debugging Criteria

Use these criteria to evaluate the quality of a debugging diagnosis.

## Diagnostic Confidence Rules

| Confidence | Criteria | Action |
| :--- | :--- | :--- |
| **High** | Hypothesis verified by direct evidence (log trace, metric spike, failing test) and related causes ruled out. | **Implement fix.** |
| **Medium** | Hypothesis consistent with symptoms and simulated tests positive, but direct evidence missing. | **Gather more logs.** |
| **Low** | Hypothesis only explains some symptoms; major contradictions remain. | **Re-run DDx.** |

## "Illness Severity" (Bug Prioritization)

| Severity | Criteria | Treatment Strategy |
| :--- | :--- | :--- |
| **CRITICAL** | Production data loss, security breach, or system-wide outage. | **Immediate mitigation first (Restart/Rollback), then root cause fix.** |
| **HIGH** | Severe performance degradation or core feature broken. | **Prioritize fix above all in-flight work.** |
| **MEDIUM** | Intermittent error or minor feature failure. | **Add monitoring/logging to catch next occurrence.** |
| **LOW** | Cosmetic or non-functional issue. | **Record in backlog for future fix.** |

## Hypotheses Quality Checklist

- [ ] **Broad Spectrum:** Did you list at least 4 hypotheses?
- [ ] **Zebra Presence:** Did you include at least one non-obvious cause?
- [ ] **Mutual Exclusivity:** Are the hypotheses distinct, or are they different symptoms of the same cause?
- [ ] **Executable Verification:** Is there at least one test for each that uses a project tool or command?


---

## Reference: templates.md

# Systematic Debugging Templates

Use this template for reporting findings during a Differential Diagnosis (DDx) session.

## Differential Diagnosis Report

```markdown
### 1. Problem Representation
**Symptom:** [User's description]
**System:** [Brief context]
**Refined Representation:** [Engineering terminology for the problem]

### 2. Hypotheses (Differential Diagnosis)
1.  **[Hypothesis 1]** (Probability: High) - [Brief reasoning]
2.  **[Hypothesis 2]** (Probability: Medium) - [Brief reasoning]
3.  **[Hypothesis 3]** (Probability: Medium) - [Brief reasoning]
4.  **[Hypothesis 4]** (Probability: Low) - [Brief reasoning]
5.  **[Hypothesis 5 (ZEBRA)]** (Probability: Very Low) - [Brief reasoning]

### 3. Top 3 Illness Scripts
1.  **[Hypothesis 1]:** [How it manifests in metrics/logs]
2.  **[Hypothesis 2]:** [How it manifests in metrics/logs]
3.  **[Hypothesis 3]:** [How it manifests in metrics/logs]

### 4. Diagnostic Tests & Verified Results
| Hypothesis | Diagnostic Test | Result (Verified/Simulated) | Finding |
| :--- | :--- | :--- | :--- |
| **H1** | [Executable test] | [Positive/Negative] | [What was found] |
| **H2** | [Executable test] | [Positive/Negative] | [What was found] |
| **H3** | [Executable test] | [Positive/Negative] | [What was found] |

### 5. Probable Diagnosis
**Conclusion:** [State the most likely root cause based on findings]
**Confidence Score:** [0-100%]

### 6. Treatment Plan
**Immediate Mitigation:** [Specific action to restore service]
**Long-term Fix:** [Specific action to prevent recurrence]
```


---