Hypothesis Tracker

State File Location

.debug-state/hypotheses.json (in project directory)

Schema

{
  "session_id": "s1",
  "started_at": "2026-02-04T10:30:00Z",
  "issue_description": "Original issue",
  "current_phase": "COLLECTING_SYMPTOMS|HYPOTHESIS_FORMED|COLLECTING_EVIDENCE|DEDUCING|VERIFYING_FIX|RESOLVED|CLEANED",
  "current_hypothesis_id": "H3",
  "hypotheses": [
    {
      "id": "H1",
      "statement": "The formData object is null at line 47",
      "formed_at": "2026-02-04T10:31:00Z",
      "status": "TESTING|PROVEN|DISPROVEN|ABANDONED",
      "verification_conditions": [
        {
          "id": "VC1",
          "statement": "formData not initialized before line 47",
          "status": "UNKNOWN|CONFIRMED|REFUTED",
          "evidence": "Evidence text",
          "evidence_source": "file:line"
        }
      ],
      "proof": "Full proof if PROVEN",
      "disproof_reason": "Why DISPROVEN",
      "led_to": "H2"
    }
  ],
  "human_inputs": [
    {
      "timestamp": "2026-02-04T10:35:00Z",
      "question": "What was asked",
      "answer": "What user said",
      "used_for": "VC1"
    }
  ],
  "conclusion": {
    "root_cause": "Definitive root cause",
    "fix_description": "What fix was applied",
    "fix_verified": true,
    "cleanup_status": "PENDING|COMPLETE",
    "resolved_at": "2026-02-04T11:15:00Z"
  }
}

Operations

Initialize Session

mkdir -p .debug-state
SESSION_ID="s$(ls .debug-state/logs 2>/dev/null | wc -l | tr -d ' ')1"

Anti-Cycle Check

Before forming a new hypothesis:

1. Load existing hypotheses
2. Check if semantically similar to any DISPROVEN hypothesis
3. If similar, require NEW evidence or different angle
4. Log connection: "informed_by": ["H1", "H2"]