The Iron Law of Systematic Debugging Methodology: A Complete Guide to Root‑Cause‑First Bug Fixing

The iron law of systematic debugging methodology mandates that no fixes may be applied before completing a thorough root‑cause investigation, requiring developers to identify the underlying origin of every bug before proposing solutions.

The OpenAI Plugins repository implements a rigorous debugging framework governed by this fundamental axiom. Embedded within the systematic‑debugging skill, the iron law establishes a non‑negotiable workflow that prioritizes diagnostic accuracy over quick patches, ensuring that every solution addresses architectural flaws rather than surface symptoms.

Defining the Iron Law of Systematic Debugging

The Core Axiom

According to the OpenAI Plugins source code, the iron law serves as the foundational rule of the systematic‑debugging skill. It states that every bug, test failure, or unexpected behavior must first undergo complete examination to discover its underlying cause. Any attempt to patch a symptom without this investigation violates the law and constitutes a fundamental failure of the debugging process. This principle is explicitly codified in plugins/superpowers/skills/systematic-debugging/SKILL.md, where the methodology strictly forbids premature fixes.

Implementation in the OpenAI Plugins Repository

Skill Definition and Enforcement

In plugins/superpowers/skills/systematic-debugging/SKILL.md, the iron law is formally established through the skill's YAML frontmatter and structural documentation. The description field explicitly restricts fix proposals until root cause analysis is complete, creating a contractual obligation for the debugging agent.

---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---

## The Iron Law

Root Cause Tracing Mechanics

The repository provides the technical implementation for Phase 1 investigation in plugins/superpowers/skills/systematic-debugging/root-cause-tracing.md. This file contains the specific techniques required to trace bugs to their origin, serving as the practical enforcement mechanism for the iron law. The plugins/superpowers/README.md provides an overview of how this skill integrates into the broader superpowers framework.

The Two‑Phase Workflow Respecting the Iron Law

The systematic debugging methodology enforces a strict sequential workflow that physically separates investigation from resolution. Phase 1 requires mandatory root cause investigation through three specific actions: reading error messages, reproducing the issue, and checking recent changes. Only after completing Phase 1 can developers legally proceed to Phase 2 for pattern analysis and solution design.

# Phase 1 – Root Cause Investigation (required first)

read_error_messages()
reproduce_issue()
check_recent_changes()

# Only after completing Phase 1 can you move to Phase 2:

# Phase 2 – Pattern Analysis

find_working_examples()
compare_to_reference()

Guard Clauses and Preventive Measures

To prevent accidental violation of the iron law, the methodology implements logical guard clauses that raise explicit failures when fixes are attempted prematurely. These programmatic checks enforce the workflow discipline required by the systematic debugging methodology.

if not phase1_completed:
    raise Exception("Fixes not allowed until root cause is identified")

Summary

• The iron law of systematic debugging methodology strictly prohibits applying fixes before completing root‑cause investigation.
• It is formally defined in plugins/superpowers/skills/systematic-debugging/SKILL.md and enforced through mandatory Phase 1 procedures.
• The methodology requires executing root cause tracing (reading errors, reproduction, change verification) before any pattern analysis or fix proposals.
• Violating this law by patching symptoms without investigation is considered a complete failure of the debugging process according to the OpenAI Plugins source code.

Frequently Asked Questions

What exactly does the iron law of systematic debugging prohibit?

The law explicitly prohibits applying any code fixes, patches, or workarounds before completing a thorough root‑cause investigation. According to the OpenAI Plugins source code, attempting to resolve a bug without first identifying its underlying origin through systematic analysis constitutes a violation of this core axiom and results in process failure.

Where is the iron law documented in the OpenAI Plugins codebase?

The iron law is formally defined in plugins/superpowers/skills/systematic-debugging/SKILL.md, which establishes the systematic‑debugging skill and its constraints. Detailed implementation guidelines for the required root‑cause tracing phase are located in plugins/superpowers/skills/systematic-debugging/root-cause-tracing.md, with broader context available in plugins/superpowers/README.md.

What is the correct workflow for following systematic debugging methodology?

Developers must execute Phase 1 (root cause investigation) by reading error messages, reproducing the issue, and checking recent changes. Only upon completing Phase 1 may they proceed to Phase 2 (pattern analysis). This sequential workflow ensures that find_working_examples() and compare_to_reference() occur after the bug's origin has been identified.

Why is violating the iron law considered a debugging failure?

The OpenAI Plugins framework treats the iron law as mandatory because fixes applied without root‑cause analysis merely mask symptoms while allowing underlying architectural flaws to persist. This enforcement ensures that solutions address the actual source of defects rather than creating temporary patches that may introduce regression errors or technical debt.

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