Skip to content

Debugging guide should distinguish "test hypothesis" from "apply fix" #3

@wtmoose

Description

@wtmoose

Friction

When an agent has a hypothesis about a bug's root cause, "test the hypothesis" is commonly misinterpreted as "implement the fix and see if it helps." This is guessing — the opposite of evidence-first debugging. The debugging guide prohibits speculative fixes but doesn't explicitly call out this failure mode.

Suggestion

Add a callout to the debugging guide or policy: "Testing a hypothesis means designing an experiment that produces discriminating evidence. It does NOT mean implementing a fix. A fix may only be applied directly when the root cause is provable by code inspection alone (e.g., a wrong parameter, a missing modifier, an incorrect identity). For performance, behavioral, or timing issues where multiple causes are plausible, runtime evidence is required before applying a fix. This evidence may require human assistance (e.g., profiling, observing UI behavior, running the app) — use the human-in-the-loop contract to request it rather than skipping the evidence step."

Affected files

Guides/Core/debugging-guide.md or Policies/debugging-process-rule.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions