/debugging

name: debugging
description: Systematic 4-phase debugging with root cause investigation. Use when fixing bugs to prevent random fixes.
version: 1.1.1
model: composer-2.5-fast
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit, Bash, Glob, Grep]
best_practices:
  - Investigate root cause before any fix
  - Reproduce the bug reliably first
  - Compare working vs broken examples
  - Make one change at a time
error_handling: strict
streaming: supported
verified: true
lastVerifiedAt: 2026-02-22T00:00:00.000Z

**Mode: Cognitive/Prompt-Driven** — No standalone utility script; use via agent context.

Systematic Debugging

Overview

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

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

Iron Laws

1. **NEVER** propose or implement a fix before completing Phase 1 root cause investigation — a fix without root cause is a guess that will fail or create new bugs. 2. **ALWAYS** reproduce the bug reliably before debugging — if you can't reproduce it consistently, you're not debugging the real issue. 3. **NEVER** make more than one change at a time when testing a hypothesis — multiple simultaneous changes make it impossible to determine which change fixed the problem. 4. **ALWAYS** stop and question the architecture after 3 failed fix attempts — if each fix reveals a new problem, the issue is architectural, not symptomatic. 5. **NEVER** skip creating a failing test case before implementing the fix — without a test, you cannot verify the fix worked or that it won't regress.

When to Use

When to Use

Use for ANY technical issue:

• Test failures
• Bugs in production
• Unexpected behavior
• Performance problems
• Build failures
• Integration issues

**Use this ESPECIALLY when:**

• Under time pressure (emergencies make guessing tempting)
• "Just one quick fix" seems obvious
• You've already tried multiple fixes
• Previous fix didn't work
• You don't fully understand the issue

**Don't skip when:**

• Issue seems simple (simple bugs have root causes too)
• You're in a hurry (rushing guarantees rework)
• Manager wants it fixed NOW (systematic is faster than thrashing)

When to Use: debugging vs smart-debug

| Scenario | Use `debugging` | Use `smart-debug` | | ------------------------------------ | --------------- | ----------------- | | Simple, locally reproducible bug | Yes | Overkill | | Root cause area already known | Yes | Optional | | Static analysis / code review bug | Yes | No | | Runtime / production issue | Start here | Preferred | | Intermittent / hard-to-reproduce | Escalate | Yes | | Needs hypothesis ranking gate | No | Yes (blocking) | | Needs instrumentation + log analysis | No | Yes | | Observability-driven (traces, APM) | No | Yes |

**Rule of thumb**: Start with `debugging` for straightforward bugs. Escalate to `smart-debug` when you need hypothesis ranking, structured instrumentation, or the bug is intermittent/production-only.

**See also**: `.claude/skills/smart-debug/SKILL.md`

The Four Phases

You MUST complete each phase before proceeding to the next.

Phase 1: Root Cause Investigation

**BEFORE attempting ANY 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 - gather more data, don't guess

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):**

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || 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 OK, workflow - build FAIL)

**For distributed/microservice systems — prefer OpenTelemetry traces:**

   # Query traces by component (preferred over manual echo/env logging)
   pnpm trace:query --component <service-name> --event <event-name> --since <ISO-8601> --limit 200

   # When trace ID is already known
   pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200

**Fragmented traces** (each service has its own root span, trace IDs don't match across boundaries) = broken context propagation. Fix `traceparent`/`tracestate` header forwarding before investigating business logic.

> **Instrumentation Gate (before hypothesis generation):** If runtime behavior remains unclear after