Systematic methodology for debugging bugs, test failures, and unexpected behavior.
Use when encountering any technical issue before proposing fixes. Covers root cause
investigation, pattern analysis, hypothesis testing, and fix implementation.
Use ESPECIALLY when under time pressure, "just one quick fix" seems obvious, or
you've already tried multiple fixes. NOT for exploratory code reading.
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# Systematic Debugging
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
## The Iron Law
```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```
If you haven't completed Phase 1, you cannot propose fixes.
---
## The Four Phases
### Phase 1: Root Cause Investigation
**BEFORE attempting ANY fix:**
1. **Read Error Messages Carefully**
- Don't skip past errors or warnings
- Read stack traces completely
- Note line numbers, file paths, error codes
2. **Reproduce Consistently**
- Can you trigger it reliably?
- What are the exact steps?
- 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**
When system has multiple components (CI -> build -> signing, API -> service -> database):
```
For EACH component boundary:
- Log what data enters component
- Log what data exits component
- Verify environment/config propagation
…
The line at the top of this page pins the label git:20251222.8a87f42, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
GET https://markdownregistry.com/api/v1/artifacts/art_nfqs5mzpefzpqvg3
GET https://markdownregistry.com/api/v1/resolve?ref=mjunaidca/mjs-agent-skills/systematic-debugging
GET https://markdownregistry.com/api/v1/blob/993e537ababe6a72ea8678bf2a4a08eaefd947f3ff70f3617a491c12df12348e
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
mjunaidca/mjs-agent-skills · .claude/skills/browsing-with-playwright/SKILL.md · Browser automation using Playwright MCP. Navigate websites, fill forms, click elements,
take screenshots, and extract…
mjunaidca/mjs-agent-skills · .claude/skills/building-chat-interfaces/SKILL.md · Build AI chat interfaces with custom backends, authentication, and context injection.
Use when integrating chat UI with…
mjunaidca/mjs-agent-skills · .claude/skills/building-chat-widgets/SKILL.md · Build interactive AI chat widgets with buttons, forms, and bidirectional actions.
Use when creating agentic UIs with…
mjunaidca/mjs-agent-skills · .claude/skills/building-chatgpt-apps/SKILL.md · Guides creation of ChatGPT Apps with interactive widgets using OpenAI Apps SDK and MCP servers.
Use when building…
mjunaidca/mjs-agent-skills · .claude/skills/building-mcp-servers/SKILL.md · Guides creation of high-quality MCP (Model Context Protocol) servers that enable LLMs
to interact with external…
mjunaidca/mjs-agent-skills · .claude/skills/building-nextjs-apps/SKILL.md · Build Next.js 16 applications with correct patterns and distinctive design. Use when creating
pages, layouts, dynamic…
mjunaidca/mjs-agent-skills · .claude/skills/building-rag-systems/SKILL.md · Build production RAG systems with semantic chunking, incremental indexing, and filtered retrieval.
Use when…
mjunaidca/mjs-agent-skills · .claude/skills/configuring-better-auth/SKILL.md · Implement OAuth 2.1 / OIDC authentication using Better Auth with MCP assistance. Use when setting
up a centralized auth…
mjunaidca/mjs-agent-skills · .claude/skills/creating-skills/SKILL.md · Guides creation of effective Agent Skills with proper structure and validation.
Use when users want to create a new…
mjunaidca/mjs-agent-skills · .claude/skills/docker/SKILL.md · Production-grade Docker containerization for Python and Node.js applications.
This skill should be used when users ask…
mvschwarz/openrig · skills/_canonical/process/systematic-debugging/SKILL.md · Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
mvschwarz/openrig · packages/daemon/specs/agents/shared/skills/process/systematic-debugging/SKILL.md · Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
cbrock84/headcount · plugins/technology/skills/systematic-debugging/SKILL.md · Finds the root cause of a bug, test failure, or unexpected behavior before proposing any fix. Use this whenever…
a5c-ai/babysitter · library/methodologies/superpowers/skills/systematic-debugging/SKILL.md · Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Requires root cause…
