antigravity-claudekit/skills/ck-debug/SKILL.md

name, description

name	description
ck-debug	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.