systematic-debugging

Systematic Debugging

This skill activates when encountering bugs, errors, unexpected behavior, or when phrases like "not working", "broken", "fix", "debug", or "investigate" appear. Also activates after 2+ failed fix attempts.

---

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Proposing solutions before completing Phase 1 violates this process. Every fix attempt without understanding the root cause is a guess—and guesses compound complexity.

---

The Four Phases

Phase 1: Root Cause Investigation

Never skip this phase. Before any fix attempt:

1. Read the error message thoroughly

   • Full stack trace, not just the first line
   • Note file paths, line numbers, variable values
   • For BOS: Check if error relates to CSS variables, React Aria, or design tokens

2. Reproduce consistently

   • Document exact steps to trigger
   • Identify if it's deterministic or intermittent
   • For BOS UI bugs: Test in both light and dark themes

3. Check recent changes

   • git diff HEAD~5 for recent modifications
   • Did we change design tokens, component props, or CSS?
   • Look for pattern: "It worked before X was changed"

4. Trace data flow

   • Follow the data from source to error
   • For BOS: CSS variable chain → Tailwind config → Component usage
   • For API: Request → Route → Service → Database → Response

5. Gather diagnostic evidence

   # For CSS/styling issues
   getComputedStyle(element).getPropertyValue('--bg-primary')
   
   # For state issues
   console.log('State:', JSON.stringify(state, null, 2))
   
   # For API issues
   curl -v endpoint | jq
   

Phase 2: Pattern Analysis

1. Find working examples

   • What similar code works correctly?
   • For BOS: Check existing components using same tokens

2. Study reference implementations

   • Read the WHOLE working example, not just the relevant line
   • For React Aria: Check their docs for correct usage patterns

3. Identify differences

   • What's different between working and broken?
   • For BOS: Compare token usage, prop shapes, class patterns