debugging

name	debugging
description	Systematic bug investigation with hypothesis tracking
license	MIT
tier	2
allowed-tools	["read_file","write_file","list_dir","search_replace","run_terminal_cmd","grep"]
related	["adventure","sniffable-python","scratchpad","research-notebook","sister-script","session-log","self-repair","play-learn-lift","constructionism"]
tags	["moollm","development","investigation","hypothesis","testing"]
inputs	{"symptom":{"type":"string","required":true,"description":"What's the observable problem?"},"context":{"type":"string","required":false,"description":"When/where does it happen?"},"expected":{"type":"string","required":false,"description":"What should happen instead?"}}
outputs	["DEBUG.yml","HYPOTHESES.md","TESTS.md","ROOT_CAUSE.md"]
templates	["DEBUG.yml.tmpl"]

🔧 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:

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

hypothesis:
  id: "hyp-001"
  claim: "The bug is caused by X"
  confidence: "high|medium|low"
  
  if_true:
    - "We would expect to see..."