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

> Master systematic debugging under time pressure with our four-phase framework. Prevent guesswork, gather evidence, and implement test-driven fixes efficiently even with looming deadlines.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-09-10

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/SKILL.md), ensuring no steps are skipped during implementation:

```python
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`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/troubleshooting/debugging.md) explicitly runs these checks, while [`plugins/vercel/skills/investigation-mode/SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/systematic-debugging/SKILL.md) with companion techniques in [`root-cause-tracing.md`](https://github.com/openai/plugins/blob/main/root-cause-tracing.md) and [`condition-based-waiting.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/systematic-debugging/SKILL.md), with supporting techniques in adjacent files like [`root-cause-tracing.md`](https://github.com/openai/plugins/blob/main/root-cause-tracing.md). The skill is listed among core Superpowers in [`plugins/superpowers/README.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/README.md) and is referenced by troubleshooting guides across the codebase, including Zoom and Vercel plugin implementations.