systematic-debugginglisted

# Systematic Debugging **Core principle:** Find root cause before attempting fixes. Symptom fixes are failure. ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` ## Phase 1: Root Cause Investigation **BEFORE attempting ANY fix:** 1. **Read Error Messages Carefully** - Read stack traces completely - Note line numbers, file paths, error codes - Don't skip warnings 2. **Reproduce Consistently** - What are the exact steps? - If not reproducible → gather more data, don't guess 3. **Check Recent Changes** - 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):** Add diagnostic instrumentation before proposing fixes: ``` For EACH component boundary: - Log what data enters/exits component - Verify environment/config propagation - Check state at each layer Run once to gather evidence → analyze → identify failing component ``` Example: ```bash # Layer 1: Workflow echo "=== Secrets available: ===" echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}" # Layer 2: Build script env | grep IDENTITY || echo "IDENTITY not in environment" # Layer 3: Signing security find-identity -v ``` 5. **Trace Data Flow** See `references/root-cause-tracing.md` for backward tracing technique. Quick version: Where does bad value