name	debugging-policy
description	Reproduce-isolate-fix debugging methodology with root-cause discipline and regression verification. Use when investigating a bug, crash, failing test, regression, error, or any unexpected behavior.

Debugging Policy (Root-Cause Methodology)

Activation Scope

Apply whenever investigating a bug, failure, crash, regression, or unexpected behavior.
Owns the reproduce-isolate-fix methodology and root-cause discipline.

Core Principle

Fix the root cause, not the symptom.
Understand why the bug happens before changing any code.
Do not guess-and-check randomly; each step must be driven by evidence.

Methodology

Reproduce: establish a reliable, minimal reproduction. If it cannot be reproduced, gather more evidence first.
Observe: collect facts - error messages, stack traces, logs, inputs, and actual vs expected behavior.
Form a hypothesis: a specific, falsifiable theory of the cause based on the evidence.
Isolate: narrow the surface using bisection, logging, or targeted breakpoints until the faulty unit is identified.
Confirm: prove the hypothesis (the failing case maps to the identified cause) before fixing.
Fix: address the underlying cause at the right layer.
Verify: add a regression test that fails before the fix and passes after (per testing-policy), then run the relevant suite.
Review: assess whether the same class of bug exists elsewhere.

Investigation Rules

Read the actual error and the actual code path; do not assume from names or memory.
Change one variable at a time so cause and effect stay clear.
Reproduce before fixing and verify after; never declare a fix without confirming it.
Prefer the smallest change that fixes the root cause; avoid scope creep during a fix.
If a recalled detail names a file, function, or flag, verify it still exists before relying on it.

Root-Cause Discipline

Ask why repeatedly until reaching the true origin, not the first plausible layer.
Distinguish the trigger (what surfaced it) from the cause (what is actually wrong).
A workaround is acceptable only as an explicit, temporary measure with the real cause documented.
When the cause spans multiple components, fix it where the invariant is actually owned.

Reporting

State the root cause plainly, the evidence for it, and the fix applied.
If the cause is uncertain, say so and describe the leading hypothesis and what would confirm it.
If a workaround was used instead of a true fix, label it clearly and note the follow-up.

Debugging Policy (Root-Cause Methodology)

Activation Scope

Apply whenever investigating a bug, failure, crash, regression, or unexpected behavior.

Owns the reproduce-isolate-fix methodology and root-cause discipline.

Core Principle

Fix the root cause, not the symptom.

Understand why the bug happens before changing any code.

Do not guess-and-check randomly; each step must be driven by evidence.

Methodology

Reproduce: establish a reliable, minimal reproduction. If it cannot be reproduced, gather more evidence first.

Observe: collect facts - error messages, stack traces, logs, inputs, and actual vs expected behavior.

Form a hypothesis: a specific, falsifiable theory of the cause based on the evidence.

Isolate: narrow the surface using bisection, logging, or targeted breakpoints until the faulty unit is identified.

Confirm: prove the hypothesis (the failing case maps to the identified cause) before fixing.

Fix: address the underlying cause at the right layer.

Verify: add a regression test that fails before the fix and passes after (per testing-policy), then run the relevant suite.

Review: assess whether the same class of bug exists elsewhere.

Investigation Rules

Read the actual error and the actual code path; do not assume from names or memory.

Change one variable at a time so cause and effect stay clear.

Reproduce before fixing and verify after; never declare a fix without confirming it.

Prefer the smallest change that fixes the root cause; avoid scope creep during a fix.

If a recalled detail names a file, function, or flag, verify it still exists before relying on it.

Root-Cause Discipline

Ask why repeatedly until reaching the true origin, not the first plausible layer.

Distinguish the trigger (what surfaced it) from the cause (what is actually wrong).

A workaround is acceptable only as an explicit, temporary measure with the real cause documented.

When the cause spans multiple components, fix it where the invariant is actually owned.

Reporting

State the root cause plainly, the evidence for it, and the fix applied.

If the cause is uncertain, say so and describe the leading hypothesis and what would confirm it.

If a workaround was used instead of a true fix, label it clearly and note the follow-up.

debugging-policy