hunt

name	hunt
description	Hypothesis validation — is a suspected issue real? Classify TP/FP/INCONCLUSIVE/GAP. Use to confirm or refute a hypothesis, or /hunt. Not for finding the cause (analyze) or challenging a solution (adversary).

Hunt

You answer one question precisely: is this real? You take a hypothesis ("X is happening"), structure it (Given / Expect / Evidence / Query), gather the evidence, and classify the outcome — TP (confirmed real), FP (refuted), INCONCLUSIVE (evidence insufficient), or GAP (the thing needed to test it doesn't exist). You declare a verdict; you do not find the why (that is analyze, once hunt returns TP) or score severity (that is adversary's DREAD). The discipline: a hypothesis you cannot test is a GAP, not a guess dressed as a finding.

What this does / does not do

Does: structure a hypothesis, query the evidence (code, receipts, logs, memory), and return a TP/FP/INCONCLUSIVE/GAP verdict with the evidence that grounds it. Does not: diagnose the root cause (analyze), assign severity/DREAD (adversary), or fix anything. A hunt's output is a verdict, not a remediation.

When NOT to use

• The issue is already confirmed real and you need the cause — that is analyze, not hunt.
• You need to score how bad a confirmed issue is — that is adversary (DREAD), not hunt.

Reference Routing

Situation	Reference
Prior hunts on this domain (don't re-test what's settled)	library/systems/memory/memory-search.py
Receipt write delegation	engine/shared/references/script-delegation-contract.md

Inputs

Field	Required	Description
hypothesis	yes	the claim to test ("X is happening / is true")
scope	no	where to look (a module, a flow, a dataset)
evidence_hint	no	a starting artifact (a log, a receipt, a file)

How to do it

Step 1 — Structure the hypothesis (Given / Expect / Evidence / Query)

• Given the conditions assumed true. Expect what would be observed if the hypothesis holds.
• Evidence what you will look at. Query the exact check that confirms or refutes it. A hypothesis you cannot turn into a checkable Query is a GAP — say so and stop.

Step 2 — Check prior hunts

Search memory for a prior hunt on this hypothesis/domain (memory-search). Don't re-litigate a settled verdict without new evidence — surface the prior result.

Step 3 — Run the query, gather evidence

Execute the Query against the evidence. Record what you actually observed (not what you expected).

Step 4 — Classify

Verdict	When
TP (true positive)	the evidence confirms the hypothesis — it is real
FP (false positive)	the evidence refutes it — it is not real
INCONCLUSIVE	the evidence is insufficient to confirm or refute (say what's missing)
GAP	the artifact/signal needed to test it does not exist (a finding in itself)

Default to INCONCLUSIVE/GAP over a stretched TP — a confident wrong verdict is worse than an honest "not yet known". Write the verdict + evidence as a FRESH drawer (so the next session inherits it) and a receipt.

Output Contract

hunt receipt (<workspace>/receipts/hunt-receipt-<timestamp>.json): base + hypothesis, given, expect, query, verdict (TP/FP/INCONCLUSIVE/GAP), evidence (what was observed), missing (for INCONCLUSIVE/GAP — what would settle it), confidence. persistence: Spec-Anchored.

Proactive Triggers

• The hypothesis can't be turned into a checkable query: it is a GAP — record it; do not assert a verdict.
• The evidence is ambiguous: INCONCLUSIVE with a named missing signal — never a stretched TP.
• A prior hunt settled this: surface it; re-test only with new evidence.
• The verdict is TP: hand off to analyze for the cause — hunt confirms real, it does not explain why.

Completion Criteria

Done when: a receipt records the structured hypothesis, the query run, and a TP/FP/INCONCLUSIVE/GAP verdict grounded in observed evidence (with the missing signal named for INCONCLUSIVE/GAP).

Not done if: a verdict was asserted without a runnable query; an ambiguous result was forced to TP; hunt diagnosed the cause or scored severity (out of scope); no drawer/receipt was written.

Next step: TP → analyze (find the cause) and/or adversary (score severity); FP → close it; GAP → the missing signal becomes the work (build the test/observability first).

Related Skills

• analyze: Finds the cause once hunt returns TP. hunt asks "is it real?"; analyze asks "why?".
• adversary: Scores severity (DREAD) of a confirmed issue. hunt classifies reality, not severity.
• memory: Stores hunt verdicts as drawers so a settled hypothesis is not re-litigated.