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. Inventory consumers of the boundary-facing functions, return types, and serialized fields before changing their representation. Preserve established contracts unless the task explicitly authorizes a migration.
5. Convert once into the canonical internal representation, such as integer minor units, and keep calculations in that representation. Keep the conversion behind the existing API when callers still depend on the prior type or unit.
6. Format display output from the canonical value. Do not reintroduce a lossy type merely for presentation.

If a public type or unit must change, treat it as a migration: update every known caller, add contract tests at the consumer boundary, and state the compatibility impact. A locally correct numeric fix that silently changes dollars to cents, seconds to milliseconds, or strings to identifiers is not complete.

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, existing typical behavior, and the pre-existing consumer contract 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.
• Do not silently change a public function's type, unit, schema, or error contract to make the local fix convenient.
• 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.