// Systematic debugging methodology for all orchestrated sub-agents. 4-phase root cause analysis: investigate → analyze → hypothesize → implement. Injected when encountering errors or during debugging phase.
Unified desktop + browser automation. Routes DOM targets to CDP (cli-jaw browser), desktop apps to Computer Use, hybrid combos to both. Codex desktop/CLI + macOS required for Computer Use.
Backend engineering guide for orchestrated sub-agents. Framework-agnostic API design, clean architecture, database optimization, security hardening, systematic debugging. Modular: SKILL.md orchestrator + references/ for deep guidance. Injected when role=backend.
Code review guide for all orchestrated sub-agents. Review process, quality thresholds, antipattern detection, giving/receiving feedback. Available to any agent regardless of role — read this SKILL.md when performing or receiving code reviews.
Data engineering and analysis guide for orchestrated sub-agents. Data pipelines, ETL/ELT design, data quality validation, SQL optimization, and analysis patterns. Injected when role=data.
Production-grade frontend with distinctive aesthetics. Detects stack and applies specialized rules. Modular: SKILL.md orchestrator + references/ for deep guidance. Injected when role=frontend.
PABCD orchestration workflow. Structured 5-phase development with user checkpoints. Injected during orchestration mode.
| name | dev-debugging |
| description | Systematic debugging methodology for all orchestrated sub-agents. 4-phase root cause analysis: investigate → analyze → hypothesize → implement. Injected when encountering errors or during debugging phase. |
This skill is the thinking process for fixing bugs. It enforces a structured 4-phase methodology for every technical issue — test failures, runtime errors, build failures, performance regressions, integration bugs.
Boundary: This skill covers how to reason about bugs. For test harness,
reproduction frameworks, and verification tooling, see dev-testing. For
domain-specific context (API errors, hydration issues, query performance),
consult dev-backend or dev-frontend.
dev-debugging = root cause methodology (the thinking)
dev-testing = test harness for reproducing/verifying (the tooling)
dev §2 = summary pointer to this skill (the overview)
Complete root cause investigation before proposing any fix. If Phase 1 is not done, keep investigating.
Complete these before attempting any fix:
Read the full error — stack trace, line numbers, error code, surrounding context. Do not skim. The answer is often in the error message itself.
Reproduce consistently — exact steps to trigger the bug. If intermittent, document frequency, conditions, and environment state. A bug you cannot reproduce is a bug you cannot verify as fixed.
Check recent changes — run git log --oneline -10 and git diff. Check
new dependencies, config changes, environment variables. Bugs correlate with
recent changes most of the time.
Trace data flow — where does the bad value originate? Trace backward from the failure point through the call stack until you find the source. Fix at the source, not the symptom.
Instrument component boundaries — for multi-layer systems (API → service → database, CI → build → deploy), log input/output at each boundary BEFORE proposing fixes.
For EACH component boundary:
- Log what data enters the component
- Log what data exits the component
- Verify environment/config propagation
Run once → analyze evidence → identify failing layer → investigate THAT layer
Work through these steps; skip only if clearly irrelevant to the problem at hand.
Find working examples — similar working code in the same codebase. If it
worked before, use git bisect to find the breaking commit (see
references/tool-guides.md).
Compare systematically — list every difference between working and broken code. No matter how small. Resist assuming "that can't matter."
Read reference docs completely — official documentation for the library, API, or framework involved. Don't skim — read the full relevant section.
Check known issues — GitHub Issues, changelogs, migration guides. Someone may have hit the same bug. Search with the exact error message.
State hypothesis explicitly — "X is the root cause because evidence Y shows Z." Write it down. If you can't articulate it clearly, you don't understand it yet.
Design a test to disprove — falsification is stronger than confirmation. What would you expect to see if your hypothesis is wrong?
Test one variable — smallest possible change, one variable at a time. Never fix multiple things at once.
If it fails → form a new hypothesis. Revert the failed change and start from clean state. Stacking fixes obscures the root cause.
Admit ignorance — "I don't understand X" is a valid finding. Research further rather than guessing. Record the open question explicitly.
Write a failing test first — the test reproduces the bug. It should fail
before the fix. Use dev-testing for TDD patterns and test harness setup.
Make the minimal fix — address the root cause, not symptoms. One logical change only.
Verify: the test passes, no regressions (run the full test suite:
npm test / pytest / equivalent).
Check for similar patterns — does the same bug class exist elsewhere in the codebase? Search for it. Fix all instances, not just the one you found.
Document — commit message explains root cause AND fix. Not "fixed bug" but "fix: race condition in session middleware caused by missing await on Redis write."
If you catch yourself doing any of these, pause — root cause investigation was likely skipped.
| Red Flag | Why It Fails |
|---|---|
| "Quick fix for now, investigate later" | First fix sets the pattern. Tech debt compounds. You won't investigate later. |
| "Just try changing X and see" | Guessing guarantees rework. You'll be back here within the hour. |
| "Add multiple changes, run tests" | Can't isolate cause if multiple variables changed. Revert, change ONE thing. |
| "It's probably X, let me fix that" | "Probably" without evidence = Phase 1 not done. Go back and trace it. |
| "I don't fully understand but this might work" | Seeing symptoms ≠ understanding root cause. Your "fix" hides the real bug. |
| "One more fix attempt" (after repeated failures) | After repeated failures, pause and reassess architecture/assumptions. See escalation below. |
| "It works on my machine" | Reproduce in the SAME environment as the failure. Local success proves nothing. |
| "Let me add a try/catch around it" | Suppressing errors is not fixing them. Find WHY it throws. |
Repeated Failure Rule: After repeated failed fix attempts, pause entirely. Each fix revealing a new problem in a different place is a sign of architectural issues, not simple bugs. Discuss with the user before attempting more fixes.
Slop debugging is spray-and-pray: guess, patch, pray, repeat.
| Instead of… | Use… |
|---|---|
| Proposing fixes before investigation | Complete Phase 1 checklist first |
| "Might be X" without evidence | "Evidence shows X because [log/trace/diff]" |
| Multiple simultaneous changes | One change at a time, revert between attempts |
| Skimming stack traces | Read every line of stack trace, note line numbers |
Silent catch blocks that suppress errors | Log with context ([module] error.message), re-throw or handle |
| Modifying failing tests to pass | Fix the code, not the test — a failing test is evidence |
| Claiming "fixed" without running verification | Run full test suite, show green output, verify the original symptom |
| Copy-pasting a fix without understanding | Understand why the fix works, then adapt to your codebase |
Wrapping try/catch around the crash site | Fix at the source — trace upstream to where the bad data originates |
| Guessing at types, nulls, or undefined values | Add diagnostic logging, inspect actual runtime values |
| "It works now" after changing something unrelated | Correlation ≠ causation — revert the change and test again |
Root cause pattern: Missing input validation lets undefined values propagate into business logic. Instrument controller/service/repository boundaries to find where the bad value enters. Compare with a working endpoint that validates input with a schema. Fix: add schema validation at the entry point, write a test that sends invalid input and expects 400.
Root cause pattern: Server renders a value (e.g., date, locale string) that differs from client-side rendering due to environment differences (UTC vs. local timezone). Compare with components that defer environment-dependent rendering to useEffect. Fix: move environment-dependent formatting into a client component.
Root cause pattern: List endpoint lazy-loads related records per item (1 query + N queries). Enable query logging to count queries, then compare with an endpoint that uses eager loading. Fix: add include/joinedload, write a test asserting bounded query count.
Root cause pattern: Test passes in isolation but fails in suite due to shared mutable state (database rows, global variables, uncleared mocks). Compare with stable tests that use transaction rollback in beforeEach/afterEach. Fix: add proper test isolation, then search for other tests missing cleanup.
git log, git diff)Don't just say "I'm stuck." Provide: symptom (exact error), reproduction steps, evidence gathered (logs, traces, bisect results), hypotheses tested (what you tried, why it failed), remaining hypotheses (untested), and a recommendation for next steps.
After resolving any bug that:
Fill out references/postmortem-template.md and include it in the PR or commit.
The goal is learning, not blame. Every postmortem must produce at least one
action item that prevents the same class of bug from recurring.
| File | When to Read | What It Covers |
|---|---|---|
references/tool-guides.md | When you need stack-specific debugger commands | Node.js inspector, Python pdb/debugpy, Chrome DevTools, git bisect, database EXPLAIN |
references/postmortem-template.md | After resolving a significant incident | Blameless postmortem template with filled example |
| Skill | Relationship |
|---|---|
dev §2 | Summary of this methodology. This skill is the full version. |
dev-testing | Phase 4 "write failing test first" → use dev-testing for test patterns and harness. dev-testing provides the tooling; this skill provides the thinking. |
dev-backend | Server-side debugging context: API errors, database issues, middleware chains. |
dev-frontend | Client-side debugging context: hydration, rendering, DevTools, layout shifts. |
dev-code-reviewer | Code review catches bugs before they ship — prevention beats debugging. |
When context is limited, preserve: (1) Core principle — no fixes without root cause, (2) 4 Phases — investigate → analyze → hypothesize → implement, (3) Repeated Failure Rule — after repeated failures, reassess, (4) one variable at a time, (5) evidence over intuition, (6) failing test first.