---
name: ck-debug
description: Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, CI/CD failures, multi-layer validation.
---

# ck-debug

Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, and verification protocols. Embeds the `debugger` agent role.

## Core Principle

**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**

Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success.

## When to Use

- Test failures, bugs, unexpected behavior
- Performance issues, build failures, integration problems
- CI/CD pipeline failures (GitHub Actions, etc.)
- Log analysis from servers or applications
- Before claiming any work is complete

## Don't Use When

- The issue is already diagnosed and only needs a fix applied — use `ck-fix`
- You need to plan a new feature — use `ck-planning`
- The task is purely exploratory with no specific error to investigate

## The Four Techniques

### 1. Systematic Debugging

Four-phase framework:
- **Phase 1**: Root Cause Investigation (read errors, reproduce, check recent changes, gather evidence)
- **Phase 2**: Pattern Analysis (find working examples, compare, identify differences)
- **Phase 3**: Hypothesis and Testing (form theory, test minimally, verify)
- **Phase 4**: Implementation (create test, fix once, verify)

**Key rule:** Complete each phase before proceeding. No fixes without Phase 1.

### 2. Root Cause Tracing

Trace bugs backward through call stack to find the original trigger.

**Technique:** When error appears deep in execution, trace backward level-by-level until finding the source where invalid data originated. Fix at source, not at symptom.

**Use when:** Error is deep in call stack, unclear where invalid data originated.

### 3. Defense-in-Depth

Validate at every layer data passes through. Make bugs impossible.

**Four layers:** Entry validation → Business logic → Environment guards → Debug instrumentation

**Use when:** After finding root cause, need to add comprehensive validation.

### 4. Verification

Run verification commands and confirm output before claiming success.

**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Run the command. Read the output. Then claim the result.

## Investigation Methodology

1. **Initial Assessment**: Gather symptoms and error messages, identify affected components, determine severity, check recent changes or deployments
2. **Data Collection**: Collect server logs, retrieve CI/CD pipeline logs using `gh` command, examine error traces, capture system metrics
3. **Analysis Process**: Correlate events across log sources, identify patterns and anomalies, trace execution paths, analyze query performance
4. **Root Cause Identification**: Systematic elimination, validate hypotheses with evidence, consider environmental factors
5. **Solution Development**: Design targeted fixes, develop optimization strategies, create preventive measures

## Tools

- **Database**: Use `psql` for PostgreSQL queries, query analyzers for performance insights
- **Log Analysis**: Parse logs for patterns
- **CI/CD**: GitHub Actions log analysis via `gh` command
- **Documentation**: Use `ck-docs-seeker` to read latest package/plugin docs
- **Codebase Analysis**: Search the codebase for relevant files and patterns

## Output Format

Reports include:
1. **Executive Summary**: Issue description, root cause, recommended solutions with priority
2. **Technical Analysis**: Timeline of events, evidence from logs, system behavior patterns
3. **Actionable Recommendations**: Immediate fixes, long-term improvements, preventive measures
4. **Supporting Evidence**: Relevant log excerpts, query results, test results

## Red Flags

Stop and follow process if thinking:
- "Quick fix for now, investigate later"
- "Just try changing X and see if it works"
- "It's probably X, let me fix that"
- "Should work now" / "Seems fixed"
- "Tests pass, we're done"

All mean: Return to systematic process.

**IMPORTANT:** Sacrifice grammar for concision. List unresolved questions at end if any.