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

Issue Type	Primary Tool	Reference
Test failures	Systematic Debugging	references/systematic-debugging/
Browser/UI bugs	Chrome DevTools + E2E Testing	references/cdp-domains.md, references/e2e-workflow/
CI/CD failures	Pipeline Analyzer	scripts/cicd/, references/cicd-troubleshooting.md
Performance issues	Performance Profiler	references/performance-guide.md
Build errors	Root Cause Tracing	references/root-cause-tracing.md
Flaky tests	Find Polluter Script	scripts/find-polluter.sh

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:

Script	Purpose
navigate.js	Navigate to URLs
screenshot.js	Capture screenshots (auto-compresses >5MB)
click.js	Click elements
fill.js	Fill form fields
evaluate.js	Execute JavaScript in page context
snapshot.js	Extract interactive elements with metadata
console.js	Monitor console messages/errors
network.js	Track HTTP requests/responses
performance.js	Measure Core Web Vitals + record traces

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

Error Pattern	Common Cause	Quick Fix
"Module not found"	Missing dependency or cache issue	Clear cache, run npm ci
"Timeout"	Job taking too long	Add caching, increase timeout
"Permission denied"	Missing permissions	Add to permissions: block
"Cannot connect to Docker"	Docker not available	Use correct runner or DinD
Intermittent failures	Flaky tests or race conditions	Add retries, fix timing issues

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

Anti-Pattern	Problem	Solution
"Quick fix for now, investigate later"	Creates more bugs than it resolves; root cause remains	Iron Law: no fixes without Phase 1. Always complete root cause investigation first
Guessing at fixes without understanding	40% first-time fix rate vs 95% systematic; 2-3 hours vs 15-30 min	Follow all 4 phases; form single hypothesis and test minimally
"Just try changing X and see if it works"	Random changes compound problems; introduce new bugs	Test ONE hypothesis at a time with smallest possible change
Adding multiple changes at once	Cannot identify which change fixed (or broke) what	One change at a time; verify after each
Skipping the test / manual verification only	No regression protection; bug will recur	Always create failing test case first (Phase 4, Step 1)
3+ failed fix attempts without stopping	Indicates wrong root cause hypothesis	STOP after 3 failures; question the architecture; return to Phase 1
Trusting "API returns 200" as success	200 status doesn't mean response shape is correct for consumer	Check actual response data, not just status; validate contracts
Proposing fixes before investigation	"I think the fix is X" skips root cause analysis	Let Phase 1 complete before suggesting any fix
Omitting the stack trace	Most information-dense debugging input discarded	Always paste exact error message, stack trace, file paths, line numbers
	Fixing at symptom, not source	Bad value originates elsewhere; symptom fix masks real problem
	Assuming "it works" after one test passes	Fix may not cover edge cases; other components may break
	Debugging without a failing test	No reproducibility; can't verify fix works or stays fixed
	Ignoring environment differences	Bug appears only in CI/production but not locally

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