Root-Cause Debugging

When code fails, agents naturally reach for symptom-masking band-aids down at the crash site: adding ad-hoc null checks, optional chaining ?., fallback defaults, or empty catch blocks. This masks defects, corrupts contracts, and leaves technical debt behind.

This skill is the protocol for finding and fixing the real defect at its source.

The 3-Step Protocol

1. Contract Alignment

Before editing code, compare the producer and consumer against the intended interface:

• Did the producer break its contract? (e.g. promised an object, emitted null or malformed data).
• Or did the consumer misread the contract? (e.g. accessed item.uuid when the interface defines item.id). Decide which side of the boundary is wrong based on system types and documented contracts.

2. Trace Upstream (Read-Only)

If the producer emitted invalid state, stop editing and trace backward along the call chain:

• Where was the bad state or malformed payload introduced?
• Inspect the upstream origin: why did it create or forward this state?
• Do not make downstream edits until you locate the exact origin of the invalid state.