Debugging

Comprehensive Debugging Skill

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

The Iron Law of Debugging

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

When to Use / Not Use

Use when:

• Test failures (unit, integration, E2E)
• Bugs in production or development
• Unexpected behavior or performance problems
• Build failures or CI/CD pipeline issues
• Browser/UI issues
• ESPECIALLY when under time pressure, "just one quick fix" seems obvious, or you've already tried multiple fixes

Do NOT use when:

• Writing new tests or setting up test frameworks -> use testing-framework
• TDD methodology or writing tests before code -> use test-driven-development
• Reviewing code quality or PRs -> use code-review
• Designing CI/CD pipelines -> use cicd-pipelines

Decision Tree

What type of issue are you debugging?
├── Test failure
│   ├── Always fails (deterministic) -> Phase 1-4 systematic debugging
│   ├── Intermittently fails (flaky) -> find-polluter.sh + timing analysis
│   └── Only fails in CI, not locally -> Environment audit (OS, runtime, services)
├── Browser/UI bug
│   ├── Visual/layout issue -> Chrome DevTools scripts + screenshot
│   ├── Console errors -> console.js monitoring
│   ├── Network/API issue -> network.js tracking
│   └── Performance issue -> performance.js + Core Web Vitals
├── CI/CD pipeline failure
│   ├── Build error (module not found, etc.) -> Root cause tracing + cache check
│   ├── Timeout -> Pipeline analyzer + caching optimization
│   ├── Permission error -> Permissions block audit
│   └── Docker connection issue -> Runner/DinD configuration
├── Performance regression
│   ├── Known when it started -> Git diff between good and current deploy
│   └── Unknown source -> Performance profiler + trace recording
├── 3+ fix attempts have failed
│   └── STOP. Question the architecture. Return to Phase 1.
└── Not a debugging problem? -> See related skills

Quick Decision Matrix

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; 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? If not reproducible, gather more data, don't guess.
3. Check Recent Changes — Git diff, recent commits, new dependencies, config changes, environmental differences.
4. Gather Evidence in Multi-Component Systems — For each component boundary: log data in, log data out, verify config propagation, check state at each layer.
5. Trace Data Flow — Where does the bad value originate? Keep tracing up until you find the source. Fix at source, not at symptom.

See references/root-cause-tracing.md for detailed backward tracing technique.

Phase 2: Pattern Analysis

1. Find working examples in same codebase
2. Compare against reference implementation COMPLETELY
3. List every difference, however small
4. Understand dependencies: settings, config, environment

Phase 3: Hypothesis and Testing

1. Form single hypothesis: "I think X is the root cause because Y"
2. Test minimally — smallest possible change to test hypothesis
3. Verify before continuing — Did it work? Yes = Phase 4, No = new hypothesis
4. When you don't know — Say "I don't understand X", don't pretend

Phase 4: Implementation

1. Create failing test case — simplest possible reproduction
2. Implement single fix — address the root cause, ONE change at a time
3. Verify fix — Test passes? No other tests broken?
4. If 3+ fixes failed — STOP and question the architecture

Browser Debugging Tools

Installation:

cd scripts/chrome-devtools && npm install

Available Scripts:

Usage:

cd scripts/chrome-devtools
node screenshot.js --url https://example.com --output ./page.png
node console.js --url https://example.com --types error,warn --duration 5000

E2E Testing Workflow

8-phase visual debugging with Playwright:

1. Discovery — Detect app type, framework (references/e2e-workflow/phase-1-discovery.md)
2. Setup — Install Playwright, generate config
3. Preflight — Validate app loads correctly
4. Generation — Create screenshot-enabled tests
5. Capture — Run tests and capture visual data
6. Analysis — LLM-powered visual analysis
7. Regression — Compare screenshots against baselines
8. Export — Package production-ready test suite

Templates: templates/e2e-testing/ | Examples: examples/e2e-testing/

CI/CD Pipeline Debugging

python3 scripts/cicd/ci_health.py --platform github --repo owner/repo
python3 scripts/cicd/pipeline_analyzer.py --platform github --workflow .github/workflows/ci.yml

Debug logging: GitHub Actions: ACTIONS_RUNNER_DEBUG=true | GitLab CI: CI_DEBUG_TRACE: "true"

Test Pollution Detection

./scripts/find-polluter.sh '.git' 'src/**/*.test.ts'

Runs tests one-by-one, stops at first polluter.

Defense-in-Depth Validation

After fixing a bug, add validation at EVERY layer:

1. Entry Point — Reject obviously invalid input at API boundary
2. Business Logic — Ensure data makes sense for this operation
3. Environment Guards — Prevent dangerous operations in specific contexts
4. Debug Instrumentation — Capture context for forensics

See references/defense-in-depth.md for complete pattern.

Verification Before Completion

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
5. ONLY THEN: Make the claim

Anti-Patterns

Red Flags — STOP and Follow Process

If you catch yourself thinking:

• "Quick fix for now, investigate later"
• "Just try changing X and see if it works"
• "Add multiple changes, run tests"
• "Skip the test, I'll manually verify"
• "It's probably X, let me fix that"
• "I don't fully understand but this might work"
• "One more fix attempt" (when already tried 2+)

ALL of these mean: STOP. Return to Phase 1.

Resource Directory

References

• references/systematic-debugging/ — Core debugging methodology
• references/root-cause-tracing.md — Backward tracing technique
• references/defense-in-depth.md — Multi-layer validation
• references/verification-before-completion.md — Verification checklist
• references/cdp-domains.md — Chrome DevTools Protocol (47 domains)
• references/puppeteer-reference.md — Puppeteer API patterns
• references/performance-guide.md — Performance debugging
• references/cicd-*.md — CI/CD specific references
• references/e2e-workflow/ — E2E testing workflow phases
• references/workflow-modules/ — AI-powered debugging modules

Scripts

• scripts/chrome-devtools/ — Browser automation scripts
• scripts/cicd/ — CI/CD analysis tools
• scripts/find-polluter.sh — Test pollution finder

Templates

• templates/e2e-testing/ — Playwright test templates
• templates/cicd/ — GitHub Actions + GitLab CI templates

Integration

• testing-framework — Set up test infrastructure debugging depends on
• test-driven-development — Write tests first; debugging handles what gets through
• code-review — Catch bugs before they reach debugging
• cicd-pipelines — Design CI/CD pipelines; debugging handles when they break
• docker-containerization — Container environments where many CI/CD bugs originate