102 lines
4.2 KiB
Markdown
102 lines
4.2 KiB
Markdown
---
|
|
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.
|