Trace Bug

Trace Bug

The first task is to reproduce what the user experiences, not to patch the first suspicious line.

Workflow

1. Capture the report, environment, expected behavior, observed behavior, frequency, and impact.
2. Reproduce the defect end to end as closely as possible to the user path. Preserve the command, inputs, logs, screenshot, or trace.
3. If it does not reproduce, vary one dimension at a time: data, timing, permissions, platform, locale, network, cache, concurrency, or version.
4. Build a hypothesis ledger before editing.
5. Instrument or inspect the boundary that most efficiently separates competing hypotheses.
6. Identify the first point where actual state diverges from expected state.
7. Add a regression test that fails for the root cause, not just the visible symptom.
8. Apply the smallest root-cause fix. Avoid unrelated refactors until green.
9. Re-run the end-user reproduction, regression, relevant suites, and adjacent failure modes.
10. Remove diagnostic code and review the final diff.

Boundary-fidelity gate

When the defect crosses a serialization, protocol, database, money, timestamp, identifier, or encoding boundary, preserve the external representation until its constraints have been validated.

1. Identify the exact boundary representation, including lexical details that downstream types may erase.
2. Parse into a lossless domain type before validation. For JSON money in Python, use json.loads(payload, parse_float=Decimal) and explicitly reject non-finite constants. Do not parse through binary float and then call Decimal(str(value)).
3. Validate the domain invariant in the lossless type. Whole-cent acceptance is a numeric invariant: 1.230 may equal 1.23, while 0.105 and 0.29000000000000001 are not whole-cent values.
4. Convert once into the canonical internal representation, such as integer minor units, and keep calculations in that representation.
5. Format display output from the canonical value. Do not reintroduce a lossy type merely for presentation.

Add an adversarial boundary regression that would pass after lossy conversion but must fail at the original boundary. Also cover accepted equivalent spellings, rejected excessive precision, non-finite values, booleans, zero floors, and existing typical behavior when relevant.

Hypothesis ledger

| Hypothesis | Prediction | Discriminating check | Result | Status |
| --- | --- | --- | --- | --- |

Statuses: untested, supported, rejected, root-cause, contributing.

Flake discipline

• Preserve seed, order, timing, machine, retries, and pass/fail history.
• A retry is diagnostic evidence, not a fix.
• Do not add sleeps when an observable condition can be awaited.
• Distinguish product nondeterminism, test pollution, environmental variance, and insufficient assertions.

Stop rules

• Do not change production code before a credible reproduction or a clearly documented substitute exists.
• Do not broaden the fix beyond the causal chain without new evidence.
• If evidence contradicts the original report, report the contradiction instead of forcing a diagnosis.
• Do not claim exact boundary validation when the parser has already discarded information required to enforce it.

Evidence packet

Return reproduction, root cause, rejected hypotheses, regression test, fix, verification commands and outcomes, adjacent risks, and any environment where the defect remains untested. For boundary defects, include the raw adversarial input and show where lossless validation occurs before canonical conversion.