timequity/root-cause-tracing

Root Cause Tracing

Overview

Bugs often manifest deep in the call stack. Your instinct is to fix where the error appears, but that's treating a symptom.

Core principle: Trace backward through the call chain until you find the original trigger, then fix at the source.

When to Use

• Error happens deep in execution (not at entry point)
• Stack trace shows long call chain
• Unclear where invalid data originated
• Need to find which code triggers the problem

The Tracing Process

1. Observe the Symptom

Error: database query failed with null user_id

2. Find Immediate Cause

What code directly causes this?

await db.query('SELECT * FROM orders WHERE user_id = ?', [userId]);

3. Ask: What Called This?

OrderService.getOrders(userId)
  → called by OrderController.list()
  → called by router.get('/orders')
  → called by auth middleware

4. Keep Tracing Up

What value was passed?

• userId = null
• Where did null come from?
• Auth middleware didn't set user on request

5. Find Original Trigger

Where did the problem originate?

// Auth middleware bug: didn't handle expired tokens
if (token.expired) {
  // Missing: return error response
  // Falls through with req.user = undefined
}

Adding Stack Traces

When you can't trace manually, add instrumentation:

async function getOrders(userId: string) {
  const stack = new Error().stack;
  console.error('DEBUG getOrders:', {
    userId,
    typeOfUserId: typeof userId,
    stack,
  });
  // ... rest of function
}

Run and capture:

npm test 2>&1 | grep 'DEBUG getOrders'

Real Example

Symptom: .git created in source directory during tests

Trace chain:

1. git init runs in process.cwd() ← empty cwd parameter
2. WorktreeManager called with empty projectDir
3. Session.create() passed empty string
4. Test accessed context.tempDir before beforeEach
5. setupTest() returns { tempDir: '' } initially

Root cause: Top-level variable initialization accessing empty value

Fix: Made tempDir a getter that throws if accessed too early

Key Principle

Found immediate cause
    ↓
Can trace one level up? → YES → Trace backwards
    ↓                              ↓
    NO                        Is this the source?
    ↓                              ↓
NEVER fix just              YES → Fix at source
the symptom                        ↓
                             Add validation at each layer
                                   ↓
                             Bug impossible

NEVER fix just where the error appears. Trace back to find the original trigger.

Stack Trace Tips

• In tests: Use console.error() not logger - logger may be suppressed
• Before operation: Log before the dangerous operation, not after it fails
• Include context: Directory, cwd, environment variables
• Capture stack: new Error().stack shows complete call chain

Integration

Used by:

• systematic-debugging - Phase 1, Step 5 calls this skill

Pairs with:

• defense-in-depth - After finding root cause, add validation at each layer