| name | ak:debug |
| description | Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, multi-layer validation, log analysis, CI/CD failures, database diagnostics, system investigation. |
| user-invocable | true |
| when_to_use | Invoke when root cause must be proven before a fix. |
| category | utilities |
| keywords | ["debug","root-cause","bugs","test-failures"] |
| languages | all |
| argument-hint | [error or issue description] |
| metadata | {"author":"agentkit","version":"4.0.0"} |
Debugging & System Investigation
Comprehensive framework combining systematic debugging, root cause tracing, defense-in-depth validation, verification protocols, and system-level investigation (logs, CI/CD, databases, performance).
Core Principle
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
Random fixes waste time and create new bugs. Find root cause, fix at source, validate at every layer, verify before claiming success.
When to Use
Code-level: Test failures, bugs, unexpected behavior, build failures, integration problems
System-level: Server errors, CI/CD pipeline failures, performance degradation, database issues, log analysis
Always: Before claiming work complete
Techniques
1. Systematic Debugging (references/systematic-debugging.md)
Four-phase framework: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → Implementation. Complete each phase before proceeding. No fixes without Phase 1.
Load when: Any bug/issue requiring investigation and fix
2. Root Cause Tracing (references/root-cause-tracing.md)
Trace bugs backward through call stack to find original trigger. Fix at source, not symptom. Includes scripts/find-polluter.sh for bisecting test pollution.
Load when: Error deep in call stack, unclear where invalid data originated
3. Defense-in-Depth (references/defense-in-depth.md)
Validate at every layer: Entry validation → Business logic → Environment guards → Debug instrumentation
Load when: After finding root cause, need comprehensive validation
4. Verification (references/verification.md)
Iron law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. Run command. Read output. Then claim result.
Load when: About to claim work complete, fixed, or passing
5. Investigation Methodology (references/investigation-methodology.md)
Five-step structured investigation for system-level issues: Initial Assessment → Data Collection → Analysis → Root Cause ID → Solution Development
Load when: Server incidents, system behavior analysis, multi-component failures
6. Log & CI/CD Analysis (references/log-and-ci-analysis.md)
Collect and analyze logs from servers, CI/CD pipelines (GitHub Actions), application layers. Tools: gh CLI, structured log queries, correlation across sources.
