| name | oms-trace |
| description | Explain why an observed failure or anomaly happened before changing anything: competing hypotheses, ranked evidence, and the cheapest probe that tells them apart. Use for regressions, silent wrong results, flaky or unreproducible behaviour, and "why did this happen" questions.
|
Trace
A fix aimed at an undiscriminated hypothesis changes code without changing the
cause, and the evidence that would have separated them is gone once the code
moves. Explain first.
Keep these apart, in writing:
- Observation — what was seen, quoted, not paraphrased.
- Hypotheses — at least two that compete.
- Evidence for / against — per hypothesis, including what is missing.
- Critical unknown — the fact keeping the leading two apart.
- Discriminating probe — the cheapest step whose result differs between
them. Run that one, not the most convenient one.
Evidence is ranked, never flat:
- A controlled reproduction.
- A primary artifact with provenance: a log line, a metric,
file:line, a
commit, a timestamp.
- Independent sources converging.
- A single inference from reading code.
- Timing, naming, resemblance to a past bug, intuition.
Try to refute your own favourite before adopting it, and down-rank any
hypothesis resting on 4–5 while stronger evidence contradicts it.
Reach for:
oms fail-ledger check --cmd "…" — has this already failed here? Exit 3 means
yes, with the prior context.oms consult --all "…" — independent hypotheses; distinct model families
fail differently, and the run reports how many actually answered.oms advise --prompt "…" — before an irreversible conclusion or a release
call.
Report the leading explanation with the tier of evidence behind it and say what
is still unknown. Never state a cause no probe has separated.
