Recipes for running Hunch

2 · Choose an enforcement level#

hunch firmness firm

No restart needed — the hook reads firmness at run time.

3 · The verification pipeline (v1.4.0+)#

The operating loop — scope → evidence → change → verify → attack → report — is injected at session start and enforced at turn end. Facts, not claims: PostToolUse records which product files were edited and whether a verify-shaped command (test / build / typecheck / plan) ran afterwards. At firm/strict, the Stop hook refuses to end a turn with unverified product edits — at most twice per turn, so a broken gate can never trap you.

HUNCH_PIPELINE=0          # kill switch, per env
hunch firmness advisory   # keep grounding, drop the gate

Docs and .claude/ / .hunch/ edits never arm the gate.

4 · Capture a decision that survives the session#

After any non-trivial choice, in your assistant:

/capture     # grilling interview: topic, rationale, rejected alternatives

Or mid-flow: hunch_capture_decision(topic) → answer the questions → hunch_record_decision(...) with the returned token.

Observe: the decision shows in hunch now, and editing a file it governs injects it — including what was rejected, so the next session doesn't re-litigate it.

5 · Turn a human correction into a permanent rule#

hunch_record_correction({ rule, scope_hint_file, severity: "blocking" })

Observe: at strict, an edit violating the rule is denied with the rule quoted back. Never Twice.

6 · Keep docs honest (doc≠graph)#

Anchor a doc to a topic:

<!-- hunch:topic auth.session-storage -->

hunch drift              # CI-gateable: stale anchors fail
hunch heal               # guided reconciliation — never rewrites prose silently
hunch reconcile-topics   # after merges: one live decision per topic

7 · Wire CI#

hunch ci                 # constraint guard on the diff
hunch drift              # doc anchors still current
hunch reconcile-topics   # merge didn't fork a topic

All exit non-zero on violation — make them required checks.

8 · Make an instruction skill actually fire#

Measured: models under-trigger skills badly — 0/20 sessions read an installed skill whose description was polite prose. If you ship a skill:

• Write the description as a pushy trigger: “MANDATORY before X — invoke FIRST, do not skip because the task looks simple.” This alone took Opus from never-reads to reads-and-passes.
• Weaker models (Haiku-class) ignore even pushy descriptions — name the skill in the prompt, or inject the content via hooks (recipe 3 is exactly this, productized).
• Never conclude a skill “doesn't help” without checking the transcript for an actual Skill invocation — availability ≠ delivery.

9 · Benchmark your own setup#

The repo ships harnesses under bench/:

npx tsx bench/run.ts --arms A,C --model claude-sonnet-5
npx tsx bench/external/run-zod.ts --arms A,S --no-repro
npx tsx bench/external/run-zod.ts --arms S --force-skill --only zod-5937

Rules learned the hard way: use --no-repro (diagnosis mode) or everything ceilings at PASS; drop tasks that fail for every arm (they measure spec-guessing, not diagnosis); verify skill invocations in transcripts before comparing arms.

10 · Private overlay (public repo, private memory)#

hunch init --private-sync   # captures go to the HUNCH_PRIVATE_DIR overlay
hunch private               # point a clone at the overlay

Observe: hunch_* tools see the union; the public repo carries only what you curate.

11 · The self-running memory loop (v1.8.0+)#

Nothing to manage. Capture happens on every commit, memory lands trusted-advisory immediately, and renames heal their own bindings:

hunch log                    # every memory move: capture · adopt · supersede · prune · repair
hunch log --diff <sha>       # what one move changed
hunch revert-move <sha>      # undo one move (local git revert, never pushed)
hunch escalations            # the decisions only YOU can make — normally empty
hunch adopt-drafts           # one-time: clear a legacy draft backlog into advisory memory
hunch push                   # the one deliberate outward step (memory auto-commits locally)

Observe: after a commit that renames a file, hunch log shows a 🔧 repair move — the bindings healed themselves; nothing went stale. In VS Code, the Hunch Memory panel is the same spine with click-to-diff, one-click revert, and the inline activate / demote / withdraw / retire authority actions.

Rule of the loop: advisory is automatic; blocking is always one explicit human click, and a repaired rule asks once for a fresh proof before it can block again.

12 · Use a local or self-hosted model#

Point Hunch at any OpenAI-compatible chat-completions endpoint. Ollama, vLLM, LM Studio, and llama.cpp work without a subscription CLI:

export HUNCH_SYNTH_PROVIDER=ollama
export HUNCH_SYNTH_BASE_URL=http://localhost:11434/v1
export HUNCH_SYNTH_MODEL=hunch-synth
export HUNCH_SYNTH_TIMEOUT_MS=300000
export HUNCH_SYNTH_MAX_TOKENS=2048

For predictable large-diff synthesis with Ollama, pin the context window in a custom model:

FROM qwen2.5-coder:latest
PARAMETER num_ctx 32768

ollama create hunch-synth -f Modelfile
hunch doctor

Observe: hunch doctor reports openai-compat and no longer warns that num_ctx is unpinned.