/cm-debugging

name: cm-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
token_budget: 1500
compressed: true
deprecated: false

Systematic Debugging

TL;DR

• **Use when** any bug, test failure, or unexpected behavior surfaces
• **Process**: reproduce → isolate → diagnose root cause → fix
• **Defense in depth**: also add a test that locks the bug
• **Next**: cm-tdd → cm-quality-gate

Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed Phase 1, you cannot propose fixes.

When to Use

Use for ANY technical issue:

• Test failures
• Bugs in production
• Unexpected behavior
• Performance problems
• Build failures
• Integration issues

**Use this ESPECIALLY when:**

• Under time pressure (emergencies make guessing tempting)
• "Just one quick fix" seems obvious
• You've already tried multiple fixes
• Previous fix didn't work
• You don't fully understand the issue

**Don't skip when:**

• Issue seems simple (simple bugs have root causes too)
• You're in a hurry (rushing guarantees rework)
• Manager wants it fixed NOW (systematic is faster than thrashing)

The Four Phases

You MUST complete each phase before proceeding to the next.

Phase 0.5: Memory Integrity Check (BEFORE blaming code)

> **BEFORE blaming code, ASK: "Could memory be causing this bug?"**

1. **SUSPECT** — Identify relevant memories:

• What module/file is the bug in?
• Read `.cm/learnings.json` filtered by that scope
• List all active learnings + decisions for this area

2. **INVESTIGATE** — Did AI follow a memory when writing buggy code?

• Check: Does the buggy code match a `prevention` pattern from any learning?
• Check: Does the buggy code follow a `decision` that may be outdated?
• If YES → that memory is a **suspect**

3. **VERIFY** — Is the suspect memory still correct?

• Compare learning with current codebase (not when it was recorded)
• Has the dependency/pattern/architecture changed since learning was recorded?
• If memory is WRONG → proceed to HEAL

4. **HEAL** (only if memory confirmed as cause):

• **Invalidate:** Set `status = "invalidated"` — learning is proven wrong
• **Correct:** Update `prevention` with correct info, set `status = "corrected"`
• **Scope-reduce:** Learning is right for smaller scope → narrow the scope
• **Record meta-learning** in `.cm/meta-learnings.json`

IF memory caused the bug:
  → HEAL memory FIRST
  → THEN proceed to Phase 1 to fix code
  → The code fix will be correct because memory is now correct

IF memory did NOT cause the bug:
  → Proceed to Phase 1 normally

> **WHY PHASE 0.5?** Fix memory first → code fix will be correct. > Without fixing memory → bug will return next session (bug loop).

Phase 1: Root Cause Investigation

**BEFORE attempting ANY fix:**

1. **Read Error Messages Carefully**

• Don't skip past errors or warnings
• They often contain the exact solution
• Read stack traces completely
• Note line numbers, file paths, error codes

2. **Reproduce Consistently**

• Can you trigger it reliably?
• What are the exact steps?
• Does it happen every time?
• If not reproducible → gather more data, don't guess

3. **Check Recent Changes**

• What changed that could cause this?
• Git diff, recent commits
• New dependencies, config changes
• Environmental differences

4. **Gather Evidence in Multi-Component Systems**

**WHEN system has multiple components (CI → build → signing, API → service → database):**

**BEFORE proposing fixes, add diagnostic instrumentation:**

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer

   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component

5. **Trace Data Flow**

**WHEN error is deep in call stack:**

• Where does bad value originate?
• What called this with bad value?
• Keep tracing up until you find the source
• Fix at source, not at symptom

Phase 2: Pattern Analysis

**Find the pattern before fixing:**

1. **Find Working Examples**

• Locate similar working code in same codebase
• What works that's similar to what's broken?

2. **Compare Against References**

• If implementing pattern, read reference implementation COMPLETELY
• Don't skim - read every line
• Understand the pattern fully before applying

3. **Identify Differences**

• What's different between working and broken?
• List every difference, however small
• Don't assume "that can't matter"

4. **Understand Dependencies**

• What other components does this need?
• What settings, config, environment?
• What assumptions does it make?

Phase 3: Hypothesis and Testing

**Scientific method:**

1. **Form Single Hypothesis**

• State clearly: "I think X is the root cause because Y"
• Write it down
• Be specific, not vague

2. **Test Minimally**

• Make the SMALLEST possible change to test hypothesis
• One variable at a time
• Don't fix multiple things at once

3. **Verify Before Continuing**

• Did it work? Yes → Phase 4
• Didn't work? Form NEW hypothesis
• DON'T add more fixes on top

4. **When You Don't Know**

• Say "I don't understand X"
• Don't pretend to know
• Ask for help
• Research more

Phase 4: Implementation

**Fix the root cause, not the symptom:**

1. **Create Failing Test Case**

• Simplest possible reproduction
• Automated test if possible
• MUST have before fixing