ha-debug

# Hope Debug

Debug from evidence, not from the first plausible explanation. This is a
decision process, not a mandatory four-stage ceremony.

## 1. Characterize The Failure

Capture the strongest available evidence:

- Exact symptom, expected behavior, and observed behavior.
- Reproduction steps, failing command, stack trace, log range, or persisted
  state.
- Whether it is deterministic, intermittent, platform-specific, data-specific,
  or timing-sensitive.
- Recent relevant diffs, dependency/config changes, and known-good boundary.

If reproduction is unsafe or requires unavailable credentials, characterize it
from logs, fixtures, state, and code paths. State the evidence gap explicitly.

## 2. Bound The Fault

Trace the smallest credible path through inputs, state transitions, persistence,
concurrency boundaries, and outputs. For multi-component systems, compare what
crosses each boundary rather than adding broad instrumentation everywhere.

Common high-value checks:

- Stale or duplicated persisted state.
- Error swallowing, fallback, retry, cancellation, and timeout paths.
- Async ordering, locks, process boundaries, and late results.
- Platform, locale, permission, path, and environment assumptions.
- Mismatch between source-of-truth data and UI projection.

## 3. Rank Falsifiable Hypotheses

Keep one or two active hypotheses. For each, write:

- Why it explains the evidence.
- What observation would disprove it.
- The cheapest discriminating check.

Run the discriminating check before editing when practical. If a tiny, obvious
fix is itself the cheapest safe experiment, keep it reversible and inspect the
result before broadening scope.

## 4. Fix The Root Cause

- Patch the smallest ownership boundary that restores the contract.
- Avoid subsystem rewrites before the fault is proven.
- Preserve unrelated user work and existing public behavior.
- Add defense-in-depth only when it covers a demonstrated adjacent failure, not
  as speculative cleanup.

After two failed fix attempts, stop patching variants. Re-read the original
evidence, challenge the shared assumption, and narrow the boundary again.

## 5. Prove The Failing Path

Use `ha-test-strategy` to choose the regression form and `ha-verify` to confirm
completion. Prefer a check that would have failed before the fix:

- Focused automated regression test.
- Existing failing command or deterministic fixture.
- Before/after database or log query.
- Manual reproduction when automation is not credible.

Passing compilation alone does not prove a runtime bug fixed. If the real path
cannot be exercised, report the strongest substitute and remaining uncertainty.

## Stop Conditions

Pause and ask for input only when progress requires inaccessible user state, an
external system change, destructive action, or a product decision. Do not invent
data or mark an unreproduced hypothesis as confirmed.

## Smoke Prompts

- "This test fails intermittently; find and fix the root cause."
- "The UI shows stale state after restart; diagnose the persistence path."
- "Use this session id and logs to explain the regression, then repair it."