hunch

🧠 Hunch (Engineering Memory)

This repo has Hunch — a curated graph of why the code is the way it is (decisions, bug history, invariants). It currently holds 193 decisions, 2 bugs, 10 constraints, 19 components, 3 policies, 1 open findings.

Consult Hunch via the hunch_* MCP tools — pick by MOMENT, not from memory:

Orient (session/task start):

• hunch_context(target) — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. Call FIRST.
• hunch_structure(target?) — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.
• hunch_runbook(task) — the proven steps for a recurring task, before re-deriving them.
• hunch_escalations() — the decisions only the HUMAN can make (including one exact imported ADR at a time, topic conflicts, and policy calls). Normally empty; when it isn't, ASK the user inline — an entry is a question, silence is never approval. Apply an ADR answer only through hunch_review_imported_adr with its printed source and review hashes.
• hunch now (CLI) — recent decisions + the live roadmap; hunch log — the memory-move timeline (every capture/adopt/supersede/prune/repair, each revertable).

Before designing / choosing an approach:

• hunch_why(target) — why a file/symbol is shaped this way (decisions, bugs, constraints) — including what was already REJECTED.
• hunch_current_decision(topic) — the one live answer for a topic (history + rejected included).
• hunch_bug_lineage(symptom_or_symbol) — has this failed before? what was the root cause?
• hunch_compare(candidates) — rank candidate branches/commits by fewest invariant hits.
• hunch_query(query) — free-text search when nothing above fits.

Before editing:

• hunch_check_constraints(scope) and hunch_get_dependents(symbol) / hunch_blast_radius(target) — invariants in scope + who you'd break. (The pre-edit hook injects this per file automatically; call these for PLANNING breadth.)
• hunch_findings(scope?) — known-but-unfixed gaps in the area (past audits, measurements, incidents) so you inherit them instead of re-discovering them.

Before committing / merging:

• hunch_conformance() — does the code still SATISFY recorded intent? Run before and after a refactor.
• hunch_policy_evaluate(policy_id?, active_only?) / hunch_policy_plan(policy_id) / hunch_policy_card(policy_id) / hunch_policy_proof(policy_id) — evaluate canonical policy, inspect the planned corpus, review the evidence/uncertainty card, and inspect raw replay receipts; only an explicit human activation grants authority.
• hunch_pr_impact(base?) / hunch_merge_verdict(...) — a change's memory surface; would it re-open a closed bug?

Build the Constitution review queue:

• hunch constitution bootstrap --since 90d --max-candidates 3 (CLI) — normalize recent structured human evidence into at most three non-active policy candidates; add --history for exact, human-identifier-grounded fix/revert deltas or explicit dependency retirements. Coincidence/ambiguity stays uncompilable; neither path grants authority.
• hunch constitution ingest --since 90d [--instructions] [--from export.json] (CLI) — normalize corrections/failures plus bounded committed instructions/ADRs and strict local review/conversation/PR exports into Git-native evidence; raw prose is hash-only, unsupported intent remains uncompilable, and no policy is minted.

After deciding / when corrected:

• hunch_capture_decision(topic?) → hunch_record_decision(...) — interview first, then write; status proposed = roadmap intent (shows in hunch now).
• hunch_record_correction(...) — a human correction becomes an ENFORCED rule (Never Twice), not a one-session memory.
• hunch_record_finding(...) — an OBSERVATION with no code change (an audit that found a gap, a measured number, an incident) becomes durable memory anchored to a date + evidence; /audit runs the ritual.
• hunch_timeline(target) — decision history when investigating how something evolved.