# The Iron Law of Systematic Debugging Methodology: A Complete Guide to Root‑Cause‑First Bug Fixing > Master the iron law of systematic debugging. Discover the root-cause-first bug fixing methodology to identify and resolve issues effectively before applying any fixes. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: deep-dive - Published: 2026-09-10 --- **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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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. ```yaml --- 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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. ```python # 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. ```python 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/systematic-debugging/root-cause-tracing.md), with broader context available in [`plugins/superpowers/README.md`](https://github.com/openai/plugins/blob/main/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.