Record a hypothesis before a fix

Before editing production code in response to a failing test, call:

hypothesis (action: record)({
  content: "<your hypothesis>",
  tddTaskId: <the id returned by tdd_task (action: start)>,
  citedTestErrorId: <test_errors.id from test_errors>,
  citedStackFrameId: <stack_frames.id from the same error>
})

Rules

1. Pass tddTaskId (the id returned by tdd_task (action: start)) — it binds the hypothesis deterministically to your task's session. Do not pass a sessionId: the field is a dev/test fallback the server ignores when host context is available, and passing the tddTaskId value under the sessionId key misattributes the hypothesis to an unrelated session. Without a tddTaskId the server still resolves the binding session from the recovered host context, so omitting both ids is acceptable; a wrong sessionId is not.
2. Both citedTestErrorId and citedStackFrameId are required. A hypothesis without specific evidence is a vibe.
3. The hypothesis should describe a causal claim. "The validation function returns null because the type guard runs before the input is normalized" is a hypothesis. "Fix the validation" is not.
4. After the fix, validate the hypothesis: hypothesis (action: validate)({ id, outcome: "confirmed" | "refuted" | "abandoned" }).

Why externalize?

The act of writing the hypothesis forces you to commit to a specific causal claim before you change code. If you can't write the hypothesis, you don't know enough to fix the bug yet — and your fix is statistically more likely to be a guess.

Reusable outside TDD

Flaky-triage and fix-failing-test workflows use this. The compliance hooks (Stop, SessionEnd) prompt for hypotheses if recent file_edits aren't cited.