debugging

Files (6)

• CARD.yml
• DEBUG.yml.tmpl
• GLANCE.yml
• README.md
• SKILL.md
• skill-snitch-report.md

SKILL.md (first lines)

# 🔧 Debugging Skill

> **"Hypothesize, test, learn, repeat."**

Debug problems methodically. Track hypotheses, test systematically, converge on root causes.

## Purpose

Debug problems methodically. Track hypotheses, document tests, record what you learn, and converge on root causes.

## When to Use

- Something isn't working as expected
- Mysterious behavior needs explanation
- Performance problems need diagnosis
- "Works on my machine" situations

## The Debugging Loop

```
OBSERVE → HYPOTHESIZE → TEST → LEARN → (repeat or) → FIX
```

### Terminal States

- `FIX` — Bug resolved
- `WONTFIX` — Intentional behavior
- `DEFER` — Not addressing now

## Protocol

### Observation Phase

Before guessing, gather facts:

```yaml
observation:
  symptom: "What's the observable problem?"
  context: "When does it happen?"
  expected: "What should happen instead?"
  
  evidence:
    - "Error message (exact text)"
    - "Logs showing the issue"
    - "Steps to reproduce"
    
  constraints:
    - "What we know for sure"
    - "What we've already ruled out"
```

### Hypothesis Tracking

```yaml
hypothesis:
  id: "hyp-001"
  claim: "The bug is caused by X"
  confidence: "high|medium|low"
  
  if_true:
    - "We would expect to see..."
    - "Changing X should fix it"
    
  test:
    action: "What to try"
    expected: "What we expect if hypothesis is correct"
    
  result:
    status: "confirmed|refuted|inconclusive"
    observation: "What actually happened"
    learned: "What this tells us"
```

### Test Documentation

```yaml
test:
  id: "test-001"
  hypothesis: "hyp-001"
  action: "What we did"
  
  before:
    state: "System state before test"
    
  after:
    state: "System state after test"
    
  result: "confirmed|refuted|inconclusive"
  learned: "What we now know"
```

## Schemas

### Observation Schema

| Field | Required | Purpose |
|-------|----------|---------|
| `symptom` | ✓ | Observable problem |
| `expected` | ✓ | What should happen |
| `error_message` | | Exact error text |
| `logs` | | Relevant log entries |
| `steps_to_reproduce` | | How to trigger |
| `constraints` | | Known facts |
| `ruled_out` | | Eliminated possibilities |

### Hypothesis Schema

| Field | Required | Purpose |
|-------|----------|---------|
| `id` | ✓ | Unique identifier |
| `claim` | ✓ | What you think is wrong |
| `test` | ✓ | How to validate |
| `confidence` | | high/medium/low |
| `if_true` | | Expected observations |
| `result` | | Test outcome |
| `learned` | | Insight gained |

### Test Schema

From SimHacker/moollm, MIT.

More from SimHacker/moollm