debugging

Files (16)

• CREATION-LOG.md
• LICENSE-addyosmani-agent-skills
• LICENSE-mattpocock-skills
• LICENSE-obra-superpowers
• SKILL.md
• SKILL.md.LICENSE
• condition-based-waiting-example.ts
• condition-based-waiting.md
• defense-in-depth.md
• find-polluter.sh
• root-cause-tracing.md
• presentation-shape.test.sh · scripts/tests/
• test-academic.md
• test-pressure-1.md
• test-pressure-2.md
• test-pressure-3.md

SKILL.md (first lines)

<!-- 本檔在契約測試底下：bash ~/.claude/skills/debugging/scripts/tests/presentation-shape.test.sh -->

# Systematic Debugging



## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** find the root cause before proposing a fix — random fixes waste time and create new bugs, and a symptom fix leaves the bug in place.

## When to Use

Use for any technical issue:
- Test failures
- Bugs in production
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues

## The Four Phases

### Phase 1: Root Cause Investigation

Before proposing a fix:

1. **Read Error Messages Carefully**
   - Don't skip past errors or warnings
   - They often contain the exact solution
   - Read stack traces completely
   - Note line numbers, file paths, error codes

2. **Reproduce Consistently**
   - Can you trigger it reliably?
   - What are the exact steps?
   - Does it happen every time?
   - If not reproducible → run the non-repro decision tree below before anything else — "gather more data" without classification is just waiting

   **Non-repro decision tree**（absorbed from addyosmani/agent-skills debugging-and-error-recovery, 2026-07-11）— classify which axis the flakiness lives on, each has different next actions:
   - **Timing-dependent（race）？** → add artificial delays to widen the race window; log event ordering with timestamps; run under load/parallelism to raise the hit rate
   - **Environment-dependent？** → diff env vars / config / dependency versions between where it fails and where it doesn't; try empty vs populated database / cache
   - **State-dependent？** → check leaked state between tests or runs; run the failing case in isolation vs after the full suite — order sensitivity is the tell
   - **Truly random？** → rare. Instrument the suspect path first (structured logging + correlation id), then wait for the next occurrence with evidence capture already in place

   Classified and instrumented → continue to step 3 (Check Recent Changes) with the evidence collected.

3. **Check Recent Changes**
   - What changed that could cause this?
   - 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):**

   **BEFORE proposing fixes, add diagnostic instrumentation:**
   ```
   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer

   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   ```

   **Example (multi-layer system):**
   ```bash
   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   [ -n "${IDENTITY:-}" ] && echo "IDENTITY: SET" || echo "IDENTITY: UNSET"   # 不用 ${IDENTITY:-UNSET}：有值時會把值印出來

   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep -q '^IDENTITY=' && echo "IDENTITY present" || echo "IDENTITY not in environment"

   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v

   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   ```

   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)

   **Redact before showing**（吸收自上游 2026-08-11；適用於本步驟與 Phase 3 證據表——所有要秀給使用者的指令、輸出、log、抓包內容）：
   - Secret 值本身（API key / password / token 值 / DSN 密碼段）不逐字出現在你顯示的輸出裡——改寫**指位**：env var 名、`.env` 路徑＋行、keychain 條目名（與 save-session 同一條規則）；同一值的非 secret 部分（host / port / db 名）照舊原樣。
   - Feedback loop 綁 env var 讓憑證留在環境不進輸出——上面 `[ -n "${IDENTITY:-}" ] && echo SET || echo UNSET` 的「印存在性不印值」就是標準形（`${VAR:-UNSET}` 有值時會印出值，不算；上游 superpowers `bb92a777` 同一修法）。
   - 帶 auth header 的 captured artifact 只引用有訊號的行。
   - 遮完不足以診斷 → 明說並問使用者，不要印出 secret。

5. **Trace Data Flow**

   **WHEN error is deep in call stack:**

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

   **Quick version:**
   - Where does bad value originate?
   - What called this with bad value?
   - Keep tracing up until you find the source
   - Fix at source, not at symptom

### Phase 2: Pattern Analysis

**Find the pattern before fixing:**

1. **Find Working Examples**
   - Locate similar working code in same codebase
   - What works that's similar to what's broken?

2. **Compare Against References**

From GGGODLIN/gggodlin-cc-harness, MIT.

More from GGGODLIN/gggodlin-cc-harness