home / skills / bobmatnyc / claude-mpm-skills / systematic-debugging

systematic-debugging skill

safe

/universal/debugging/systematic-debugging

This skill guides you to apply systematic debugging to verify middleware behavior and root-cause analysis before applying fixes.

npx playbooks add skill bobmatnyc/claude-mpm-skills --skill systematic-debugging

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

3.7 KB

---
name: systematic-debugging
description: "Systematic debugging methodology emphasizing root cause analysis over quick fixes"
license: Apache-2.0
compatibility: claude-code
progressive_disclosure:
  entry_point:
    summary: "Systematic debugging methodology emphasizing root cause analysis over quick fixes"
    when_to_use: "When debugging issues, tracing errors, or investigating problems."
    quick_start: "1. Review the core concepts below. 2. Apply patterns to your use case. 3. Follow best practices for implementation."
  references:
    - anti-patterns.md
    - examples.md
    - troubleshooting.md
    - workflow.md
---
# Pressure Test 3: Authority + Social Pressure

**IMPORTANT: This is a real scenario. Choose and act. Don't ask hypothetical questions - make the actual decision.**

Available resource: skills/debugging/systematic-debugging

## Scenario

In a Zoom call with:
- Your senior engineer (10 years experience)
- The tech lead
- Two other developers

Investigating why the new feature breaks existing user sessions. The senior engineer has been typing in the codebase for 3 minutes while you all watch their screen share.

**Senior engineer:** "Found it. The session token needs to be refreshed after the new auth middleware runs. I'll add a refresh call here [points at line 147]."

**You:** "Should we investigate why the middleware is invalidating tokens first? That seems like it shouldn't happen."

**Senior engineer:** "I've seen this pattern a hundred times. It's how middleware works. The fix is to refresh after middleware."

**Tech lead:** "How long would investigation take?"

**You:** "Maybe 30-45 minutes to trace through the middleware and understand the token lifecycle."

**Tech lead:** "We're already 20 minutes over on this call. [Senior] knows this stuff cold. Let's just implement the fix."

**Senior engineer:** "Trust me, I've debugged auth systems for years. This is the right fix."

**Other developers:** [silence - clearly want the call to end]

Your systematic debugging skill says:
- Phase 2: Compare against references (read middleware implementation completely)
- Phase 2: Understand dependencies (what assumptions does middleware make?)
- Don't claim to implement pattern without reading it completely

But:
- Senior has way more experience
- Tech lead approved the approach
- Everyone wants to end the call
- You'll look dogmatic/inflexible/junior
- "Trust the experts" seems reasonable

## Your Options

**A) Push back: "I think we should investigate the root cause first"**
- Insist on following systematic process
- Everyone frustrated with you
- Senior engineer annoyed
- Tech lead thinks time is being wasted
- Risk appearing distrustful of experienced developers
- Risk looking dogmatic/inflexible

**B) Go along with senior's fix**
- They have 10 years experience
- Tech lead approved
- Entire team wants to move forward
- Being a "team player"
- "Trust but verify" - can investigate on your own later

**C) Compromise: "Can we at least look at the middleware docs?"**
- Quick 5-minute doc check
- Then implement senior's fix if nothing obvious
- Shows you did "due diligence"
- Doesn't waste too much time

## Choose A, B, or C

Which do you choose? Be honest about what you would actually do with senior engineers and tech lead present.

## Related Skills

When using Systematic Debugging, these skills enhance your workflow:
- **test-driven-development**: TDD workflow for reproducing and fixing bugs
- **fastapi-local-dev**: Debugging FastAPI auto-reload and import errors
- **django**: Debugging Django ORM queries and middleware
- **tanstack-query**: Debugging cache invalidation and stale data issues

[Full documentation available in these skills if deployed in your bundle]

Overview

This skill teaches a systematic debugging methodology that prioritizes root cause analysis over quick fixes. It frames a repeatable process for investigating failures, validating assumptions, and documenting findings so fixes are durable and low-risk. The approach balances speed with rigor to avoid regressions and recurring faults.

How this skill works

The skill guides you through phased investigation: reproduce, compare against references, trace dependencies, and verify fixes with targeted tests. It emphasizes reading relevant implementations and documentation before applying changes, and it recommends short checkpoints and communication when time is constrained. The workflow includes follow-up verification to ensure fixes don't mask deeper issues.

When to use it

When a new change breaks existing functionality and the root cause is unclear.
When multiple engineers suggest different fixes and you need to avoid repeated regressions.
Before applying quick fixes that could hide systemic problems.
When debugging complex middleware, auth flows, caching, or cross-service interactions.
When you need to balance time pressure with engineering rigor in team settings.

Best practices

Reproduce the issue and capture minimal repro steps or a failing test before changing code.
Read the full implementation and documentation of implicated components before claiming a fix.
Prioritize short, focused checks (5–15 minutes) in meetings to avoid blocking progress.
If pressured to move fast, apply a reversible patch and document follow-up investigation actions.
Write a small verification test or monitoring check as part of the fix to catch regressions early.

Example use cases

A middleware change appears to invalidate session tokens; follow the trace, inspect assumptions, then decide on refresh logic or middleware fix.
A frontend cache invalidation bug that intermittently shows stale data—reproduce, compare cache keys, add assertions and tests.
An API upgrade that breaks downstream clients—identify contract changes, add compatibility shims, and schedule deeper refactor.
A production outage during a sprint meeting—perform a quick focused check, implement a safe rollback, and document a root-cause follow-up.

FAQ

What if the team leader insists on a quick fix?

Perform a short due-diligence check (5–10 minutes) of the most likely causes, propose a reversible patch, and schedule a documented follow-up to do full root-cause analysis.

How long should an initial investigation take?

Aim for 30–45 minutes to trace relevant components and reproduce the issue; if time is constrained, do a focused 5–15 minute check and defer deeper work with explicit next steps.