Fault Diagnosis

Fault Diagnosis

Overview

Guessing at fixes wastes time and introduces new defects. Quick patches mask underlying problems.

Core principle: ALWAYS identify root cause before attempting any fix. Treating symptoms is failure.

No exceptions. No workarounds. No shortcuts.

The Prime Directive

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you have not completed Phase 1, you are not authorized to propose fixes.

When to Use

Apply to ANY technical issue:

• Test failures
• Production bugs
• Unexpected behavior
• Performance degradation
• Build failures
• Integration breakdowns

Especially important when:

• Under time pressure (urgency makes guessing tempting)
• "Just one quick fix" seems obvious
• You have already attempted multiple fixes
• A previous fix did not resolve the issue
• You do not fully understand the problem

Do not skip when:

• The issue appears simple (simple bugs have root causes too)
• You are in a hurry (systematic investigation is faster than flailing)
• Someone wants it resolved NOW (methodical work is faster than thrashing)

The Four Phases

You MUST complete each phase before advancing to the next.

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

1. Read Error Messages Thoroughly

   • Do not skip past errors or warnings
   • They frequently contain the exact answer
   • Read stack traces completely
   • Note line numbers, file paths, error codes

2. Reproduce Reliably

   • Can you trigger it consistently?
   • What are the exact reproduction steps?
   • Does it happen every time?
   • If not reproducible, gather more data -- do not guess

3. Examine Recent Changes

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

4. Gather Evidence in Multi-Component Systems

   WHEN the system has multiple components (CI -> build -> signing, API -> service -> database):

   BEFORE proposing fixes, add diagnostic instrumentation:

   For EACH component boundary:
     - Log what data enters the component
     - Log what data exits the component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to collect evidence showing WHERE it breaks
   THEN analyze evidence to identify the failing component
   THEN investigate that specific component

   Example (multi-layer system):

   # Layer 1: Orchestrator
   echo "=== Orchestrator state: ==="
   echo "TOKEN: ${TOKEN:+SET}${TOKEN:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Build environment: ==="
   env | grep TOKEN || echo "TOKEN not in environment"
   
   # Layer 3: Signing module
   echo "=== Certificate state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual operation
   codesign --sign "$IDENTITY" --verbose=4 "$ARTIFACT"

   This reveals: Which layer fails (secrets -> orchestrator OK, orchestrator -> build FAIL)

5. Trace Data Flow

   WHEN the error is deep in the call stack:

   See root-cause-tracing.md in this directory for the complete backward tracing method.

   Short version:

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

Phase 2: Pattern Analysis

Find the pattern before fixing:

1. Locate Working Examples

   • Find similar working code in the same codebase
   • What works that resembles what is broken?

2. Compare Against References

   • If implementing a pattern, read the reference implementation COMPLETELY
   • Do not skim -- read every line
   • Understand the pattern fully before applying

3. Identify Differences

   • What differs between working and broken?
   • List every difference, no matter how small
   • Do not assume "that cannot matter"

4. Understand Dependencies

   • What other components does this require?
   • What settings, configuration, environment?
   • What assumptions does it make?

Phase 3: Hypothesis and Testing

Scientific method:

1. Form a Single Hypothesis

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

2. Test Minimally

   • Make the SMALLEST possible change to test the hypothesis
   • One variable at a time
   • Do not fix multiple things simultaneously

3. Verify Before Continuing

   • Did it work? Yes -> Phase 4
   • Did not work? Form a NEW hypothesis
   • DO NOT pile additional fixes on top

4. When You Do Not Know

   • Say "I do not understand X"
   • Do not pretend to know
   • Ask for help
   • Research further

Phase 4: Implementation

Fix the root cause, not the symptom:

1. Create a Failing Test Case

   • Simplest possible reproduction
   • Automated test if possible
   • One-off test script if no framework available
   • MUST exist before fixing
   • Use the godmode:test-first skill for writing proper failing tests

2. Implement a Single Fix

   • Address the root cause identified
   • ONE change at a time
   • No "while I'm here" improvements
   • No bundled refactoring

3. Verify the Fix

   • Test passes now?
   • No other tests broken?
   • Issue actually resolved?

4. If the Fix Does Not Work

   • STOP
   • Count: How many fixes have you attempted?
   • If < 3: Return to Phase 1, re-analyze with new information
   • If >= 3: STOP and question the architecture (step 5 below)
   • DO NOT attempt fix #4 without architectural discussion

5. If 3+ Fixes Failed: Question Architecture

   Pattern indicating an architectural problem:

   • Each fix reveals new shared state/coupling/problems in different locations
   • Fixes require "massive refactoring" to implement
   • Each fix creates new symptoms elsewhere

   STOP and question fundamentals:

   • Is this pattern fundamentally sound?
   • Are we persisting through sheer inertia?
   • Should we refactor the architecture vs. continue fixing symptoms?

   Discuss with your human partner before attempting more fixes

   This is NOT a failed hypothesis -- this is a flawed architecture.