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."
1---2name: ha-debug3description: Hope-native debugging for code failures, regressions, crashes, flaky behavior, and bad output: reproduce or characterize, rank falsifiable hypotheses, fix the smallest root cause, and prove the failing path.4---5
6# Hope Debug
7
8Debug from evidence, not from the first plausible explanation. This is a
9decision process, not a mandatory four-stage ceremony.
10
11## 1. Characterize The Failure
12
13Capture the strongest available evidence:
14
15- Exact symptom, expected behavior, and observed behavior.
16- Reproduction steps, failing command, stack trace, log range, or persisted
17 state.
18- Whether it is deterministic, intermittent, platform-specific, data-specific,
19 or timing-sensitive.
20- Recent relevant diffs, dependency/config changes, and known-good boundary.
21
22If reproduction is unsafe or requires unavailable credentials, characterize it
23from logs, fixtures, state, and code paths. State the evidence gap explicitly.
24
25## 2. Bound The Fault
26
27Trace the smallest credible path through inputs, state transitions, persistence,
28concurrency boundaries, and outputs. For multi-component systems, compare what
29crosses each boundary rather than adding broad instrumentation everywhere.
30
31Common high-value checks:
32
33- Stale or duplicated persisted state.
34- Error swallowing, fallback, retry, cancellation, and timeout paths.
35- Async ordering, locks, process boundaries, and late results.
36- Platform, locale, permission, path, and environment assumptions.
37- Mismatch between source-of-truth data and UI projection.
38
39## 3. Rank Falsifiable Hypotheses
40
41Keep one or two active hypotheses. For each, write:
42
43- Why it explains the evidence.
44- What observation would disprove it.
45- The cheapest discriminating check.
46
47Run the discriminating check before editing when practical. If a tiny, obvious
48fix is itself the cheapest safe experiment, keep it reversible and inspect the
49result before broadening scope.
50
51## 4. Fix The Root Cause
52
53- Patch the smallest ownership boundary that restores the contract.
54- Avoid subsystem rewrites before the fault is proven.
55- Preserve unrelated user work and existing public behavior.
56- Add defense-in-depth only when it covers a demonstrated adjacent failure, not
57 as speculative cleanup.
58
59After two failed fix attempts, stop patching variants. Re-read the original
60evidence, challenge the shared assumption, and narrow the boundary again.
61
62## 5. Prove The Failing Path
63
64Use `ha-test-strategy` to choose the regression form and `ha-verify` to confirm
65completion. Prefer a check that would have failed before the fix:
66
67- Focused automated regression test.
68- Existing failing command or deterministic fixture.
69- Before/after database or log query.
70- Manual reproduction when automation is not credible.
71
72Passing compilation alone does not prove a runtime bug fixed. If the real path
73cannot be exercised, report the strongest substitute and remaining uncertainty.
74
75## Stop Conditions
76
77Pause and ask for input only when progress requires inaccessible user state, an
78external system change, destructive action, or a product decision. Do not invent
79data or mark an unreproduced hypothesis as confirmed.
80
81## Smoke Prompts
82
83- "This test fails intermittently; find and fix the root cause."
84- "The UI shows stale state after restart; diagnose the persistence path."
85- "Use this session id and logs to explain the regression, then repair it."
shiwenwen