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 · Connect the team-memory Matrix#

Create a dedicated private Git repository for memory. It must differ from every code-repo remote, and its committed URL must not contain credentials. On one maintainer machine:

npm i -g @davesheffer/hunch@1.18.1
hunch shared --repo git@github.com:acme/project-hunch-memory.git
git add .gitignore .hunch/team.json
git commit -m "chore: connect shared Hunch memory"
git push

Add --migrate only when moving existing public .hunch/ memory into the dedicated store. On every teammate machine:

npm i -g @davesheffer/hunch@1.18.1
git pull
hunch init
hunch doctor

Observe: the code repo commits only .hunch/team.json; credentials remain in SSH or the Git credential helper. Each machine gets an ignored memory clone and local pointer. CLI operations refresh at startup, MCP tools refresh at request boundaries, and captures synchronize automatically.

For a coordinated pause or rollback that preserves every memory record:

hunch firmness off
hunch shared --repo git@github.com:acme/project-hunch-memory.git --no-auto-commit
npm i -g @davesheffer/hunch@1.16.0

Revert the .hunch/team.json setup commit only if new clones must stop discovering the Matrix. Do not delete the memory repo or local overlay; after upgrading every client to the same current release, hunch shared --sync publishes pending memory.

11 · 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.

12 · 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.

13 · 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.

14 · Install the editor companion and verify a release#

Install Hunch from Open VSX, then open a repository initialized with the Hunch CLI. The extension reads the same public, private, or Matrix memory home and never writes Hunch JSON directly.

npm view @davesheffer/hunch@1.18.1 version dist.integrity dist.attestations --json
git tag --list v1.18.1 vscode-v0.17.3

Observe: npm reports version 1.18.1, an integrity digest, and provenance metadata; Open VSX reports 0.17.3. Each tag’s GitHub Actions run validates the exact content-addressed artifact before isolated publishing begins and verifies the same public bytes afterward.