Systematic Debugging Under Time Pressure: A Four-Phase Framework for Root-Cause Analysis

Systematic debugging is a four-phase root-cause process that prevents guesswork by enforcing evidence gathering and test-driven fixes, even when shipping deadlines loom.

In the openai/plugins repository, the systematic-debugging skill codifies a disciplined troubleshooting methodology designed specifically for high-pressure scenarios. Located at plugins/superpowers/skills/systematic-debugging/SKILL.md, this framework mandates a rigorous investigation sequence that stops developers from jumping to "quick fixes" when managers demand immediate resolution.

The Iron Law of Root-Cause Investigation

The foundation of the methodology is the Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. This rule appears in the first phase of the skill documentation and serves as a hard barrier against the natural impulse to patch symptoms when time is short. By forcing engineers to gather concrete evidence before touching code, the process eliminates the trial-and-error cycles that typically consume hours under deadline pressure.

The Four-Phase Process Defined in SKILL.md

The systematic-debugging skill structures troubleshooting into four distinct phases, each with explicit success indicators and exit criteria.

Phase 1 – Root Cause Investigation

This phase mandates reproducible steps, full error-message analysis, inspection of recent changes, and instrumentation at component boundaries. Success is achieved only when you understand both what failed and why it failed. The companion document root-cause-tracing.md provides concrete backward-tracing techniques referenced in this phase.

Phase 2 – Pattern Analysis

Engineers must locate working examples, compare them against the broken implementation, list all differences, and verify dependencies. This creates a clear map of correct versus incorrect behavior, preventing the assumption that "if it compiled yesterday, the code is fine."

Phase 3 – Hypothesis & Testing

You must form a single, testable hypothesis and make the smallest possible change to verify it. This constraint prevents the "shotgun debugging" approach where multiple variables change simultaneously, making it impossible to determine which modification actually resolved the issue.

Phase 4 – Implementation

Before applying any fix, the process requires creating a failing test case (Phase 4.1) to guarantee the bug is verifiable and repeatable. If three consecutive fixes fail, the framework mandates reconsidering the architecture rather than adding another patch. This prevents endless refactoring loops that derail time-sensitive releases.

How Systematic Debugging Prevents Time-Pressure Failures

Under time pressure, teams typically skip investigation and jump to patches. The systematic-debugging skill counters these failure modes through enforced discipline:

Time-Pressured Scenario	Typical Response	Systematic Debugging Approach
Manager demands immediate fix	Engineers guess causes and deploy "quick-fix" patches	The Iron Law forces evidence gathering first, eliminating rework from false assumptions
Intermittent bug appears	Teams retry random changes, increasing noise	Phase 1 mandates reproducible steps and boundary instrumentation, reducing trial-and-error cycles dramatically
Multiple fixes already failed	Confidence erodes; developers add "one more" change blindly	Phase 4 triggers architectural review after three failures, preventing infinite debugging loops
Fast resolution required	Temptation to skip testing and deploy directly	Phase 4.1 requires a failing test case before fixes, ensuring verifiable, stable resolutions

Implementing the Process in Plugin Development

The skill integrates directly into the plugin architecture through manifest declarations and programmatic APIs.

Declaring the Skill in plugin.json

To enable systematic debugging for a plugin, reference the skill in the manifest:

{
  "name": "example-plugin",
  "description": "Demonstrates systematic debugging usage.",
  "skills": [
    "systematic-debugging",
    "defense-in-depth"
  ],
  "manifestVersion": "v1"
}

This declaration tells the runtime to enforce the four-phase checklist whenever error conditions are detected.

Programmatic Usage in Python

The following skeleton mirrors the phases described in SKILL.md, ensuring no steps are skipped during implementation:

from superpowers.skills import systematic_debugging as sd

def handle_error(exc):
    # Phase 1 – gather evidence

    sd.investigate_root_cause(error=exc)
    
    # Phase 2 – locate pattern

    sd.analyze_pattern(example_path="plugins/example/working_example.py")
    
    # Phase 3 – formulate hypothesis

    hypothesis = "Missing env var causes KeyError"
    sd.test_hypothesis(
        hypothesis, 
        change=lambda: os.environ.update({"MY_VAR": "value"})
    )
    
    # Phase 4 – implement fix

    sd.create_failing_test(test_name="test_missing_env")
    sd.apply_fix(lambda: os.environ.setdefault("MY_VAR", "default"))
    sd.verify_fix()

Many plugins embed "5-Minute Runbook" pre-flight checks that invoke this process before deep debugging. For example, plugins/zoom/skills/zoom-apps-sdk/troubleshooting/debugging.md explicitly runs these checks, while plugins/vercel/skills/investigation-mode/SKILL.md orchestrates systematic debugging across runtime logs, workflow steps, and browser verification.

Summary

• Systematic debugging enforces a four-phase root-cause investigation that prevents guesswork under time pressure.
• The Iron Law prohibits any code changes before completing Phase 1 evidence gathering.
• Phase 4.1 mandates creating a failing test case before applying fixes, ensuring verifiable resolutions.
• The three-strike rule (after three failed fixes, reconsider architecture) prevents infinite debugging loops.
• Implementation resides in plugins/superpowers/skills/systematic-debugging/SKILL.md with companion techniques in root-cause-tracing.md and condition-based-waiting.md.

Frequently Asked Questions

What is the "Iron Law" in systematic debugging?

The Iron Law is the strict requirement that engineers perform root-cause investigation before writing any fix. According to plugins/superpowers/skills/systematic-debugging/SKILL.md, this rule prevents the "quick-fix" patches that often introduce regressions when developers guess at causes under deadline pressure.

How does systematic debugging handle intermittent bugs?

Phase 1 (Root Cause Investigation) mandates creating reproducible steps and instrumenting component boundaries rather than retrying random changes. This structured approach replaces the typical trial-and-error cycle that wastes time on non-deterministic failures.

Why must I write a failing test before fixing the bug?

Phase 4.1 requires a failing test case to ensure the bug is actually understood and verifiable. This guarantees that the fix addresses the root cause rather than a symptom, and provides a regression test to prevent future incidents. The skill explicitly warns against implementing fixes without this verification step.

Where is the systematic debugging skill defined in the OpenAI Plugins repository?

The primary definition lives in plugins/superpowers/skills/systematic-debugging/SKILL.md, with supporting techniques in adjacent files like root-cause-tracing.md. The skill is listed among core Superpowers in plugins/superpowers/README.md and is referenced by troubleshooting guides across the codebase, including Zoom and Vercel plugin implementations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}