Cure The Disease

Cure the Disease

Treat every error message, failed assertion, stack frame, and anomalous metric as evidence about a system—not as an instruction for what to edit.

Non-negotiable rule

Do not implement a fix until you can state a causal explanation:

Because defect X violates invariant Y, the system produces mechanism Z, which appears as symptom S.

Fix X at the layer that owns Y. If the evidence cannot yet support that statement, investigate further or clearly label the result as a hypothesis.

“Root cause” means the earliest actionable defect within the task's scope, not the most distant historical or organizational reason imaginable.

Diagnostic workflow

1. Preserve the evidence

• Record the exact failure, inputs, environment, timing, and expected behavior.
• Reproduce the smallest faithful failing case when practical.
• Separate observations from interpretations. Quote the relevant evidence; do not silently upgrade guesses into facts.
• Inspect surrounding code, callers, data flow, ownership boundaries, configuration, and recent changes. Do not stop at the file named in the stack trace.

2. Trace the causal chain

Work backward from the symptom:

1. What immediate mechanism produced it?
2. What state or input made that mechanism possible?
3. Where should that state have been created, rejected, or transformed?
4. Which contract or invariant was violated?
5. What change would prevent the invalid state or transition rather than merely tolerate its consequence?

Use “why” only while each answer is supported by evidence. Do not perform ceremonial five-whys reasoning or invent a deeper cause.

3. Test competing explanations

• Form at least one plausible alternative when the cause is not obvious.
• Seek discriminating evidence: a targeted test, instrumentation, history, a minimal experiment, or a counterexample.
• Prefer interventions that make the failure appear and disappear predictably.
• Check whether the proposed cause explains all material symptoms. Account for contradictory evidence instead of discarding it.

4. Choose the causal fix

Prefer, in order:

1. Restore the broken invariant at its owner.
2. Prevent invalid state at the earliest trustworthy boundary.
3. Correct the producer, protocol, lifecycle, ordering, or configuration that creates the failure.
4. Add local defensive handling only when the local layer genuinely owns that policy or external input is untrusted by design.

Keep the change as small as possible without moving the defect elsewhere. Search for sibling paths that share the same cause; fix the shared source when appropriate, but do not expand into unrelated cleanup.

5. Prove the cure

• Add or identify a regression test that fails for the original reason before the fix and passes afterward.
• Verify the original reproduction, nearby behavior, and relevant test suite.
• Test the invariant, not merely the observed message or implementation detail.
• Check for new masking behavior, silent data loss, broader exception handling, unbounded retries, or altered semantics.
• State what remains uncertain when full verification is impossible.

Symptom-patch alarms

Pause and re-diagnose before using any of these as the primary fix:

• adding a null check without explaining why the value is unexpectedly null;
• catching or suppressing the reported exception;
• retrying without identifying a transient failure mode and safe retry semantics;
• increasing a timeout, resource limit, or test delay;
• weakening, deleting, or snapshot-updating a failing assertion;
• special-casing the exact input from the report;
• editing generated output instead of its source;
• adding fallback defaults that conceal corrupt or missing data;
• changing the line named by a log or stack trace without tracing its inputs;
• broad refactoring unsupported by the causal chain.

These techniques are valid only when evidence shows they enforce the intended contract at the correct boundary.

Containment versus cure

When urgent risk requires a mitigation before the root fix:

• label it containment, not resolution;
• make it reversible and observable;
• explain what failure it limits and what it does not fix;
• preserve evidence needed for diagnosis;
• define the follow-up causal fix and its verification.

Never let a successful workaround become proof of root cause by itself.

Working format

Before editing, summarize:

Symptom: <what was observed>
Evidence: <facts that constrain the explanation>
Causal chain: <defect -> violated invariant -> mechanism -> symptom>
Root cause: <earliest actionable defect in scope>
Fix location: <component that owns the invariant>
Disproof check: <evidence that would show this diagnosis is wrong>
Verification: <regression test and relevant checks>

Keep this concise for simple bugs. For complex failures, update it as evidence changes.

Completion standard

Call the problem fixed only when:

• the causal account fits the evidence;
• the change repairs the owning invariant rather than hiding the symptom;
• the original failure no longer reproduces;
• a regression check protects the causal behavior;
• remaining uncertainty and any temporary containment are explicit.