misfire — trace-grounded CLAUDE.md adherence auditor

misfire

Linters tell you your rules are messy; misfire tells you which rules your agents actually ignore — and converts only those into hooks, keeping safety rules.

misfire is a deterministic, local-first CLI and Python library that reads your existing Claude Code instruction files (CLAUDE.md, .claude/rules/*.md, @imports) and your own run history, then tells you which of YOUR prose rules your agents demonstrably ignore, ranked from YOUR run history. For the violated, machine-checkable subset only, it scaffolds a deterministic hook for you to review — keeping safety and judgment rules as prose. It is an observer and recommender: it prints recommendations, ranked violation lists, and hook scaffolds. It never auto-deletes a rule, never auto-applies a change, and never writes settings.json.

The static audit (stale paths, token rent, conflicts) and the hook scaffold are table-stakes features bundled under one headline: trace-grounded adherence measurement of your existing prose rules. No shipping tool ranks which of your existing prose rules your agents actually ignore.

Why now

Convert-to-hook is Anthropic's own guidance. The Claude Code best-practices docs say that bloated CLAUDE.md files cause Claude to ignore your actual instructions, and that the fix is to "delete it or convert it to a hook" — because hooks are deterministic while CLAUDE.md is advisory. The /memory docs describe CLAUDE.md as "context, not enforced configuration" and note that going over 200 lines reduces adherence. The "Effective context engineering" guidance frames the same problem as a finite "attention budget" subject to "context rot."

So the idea of converting rules to hooks is not new, and misfire says so plainly. The honest why-now is narrower and is the whole story: no credible public measurement of CLAUDE.md adherence exists. misfire producing the first trace-grounded adherence ranking from your own run history is the differentiator — not the hook scaffold, which is official guidance, but the evidence-grounding that decides which rules earn a hook.

What misfire does

Four commands, each with a deterministic --json mode (sorted keys, byte-stable output):

Command	What it does
audit	Static, zero-LLM audit of your instruction files — finds stale_path, token_rent, conflict, and load_fidelity issues. Table-stakes.
rank	Reconstructs rule violations from your run history and ranks the machine-checkable rules by observed violation rate, with confidence thresholds and a minimum-support floor. This is the wedge.
evidence	Shows the per-rule violation detail behind a ranking — the actual tool actions that violated a rule.
convert	Scaffolds a deterministic PreToolUse/PostToolUse hook for the violated convertible subset, prints it plus a settings.json snippet for you to review, and writes nothing.

Plus one opt-in, non-deterministic command, off the default path:

Command	What it does
ablate	[opt-in; requires a running local Ollama] Causal probe — re-runs a representative task with a candidate rule present vs. removed (ablated) and measures the shift in how often a local model violates the rule. Estimates a rule's marginal effect, which passive traces can't (an obeyed rule and a never-triggered rule both show zero violations). Evidence only — never auto-applies or auto-deletes.

Observer exit codes: every command exits 0 regardless of findings. The only non-zero exit is evidence or convert invoked with an explicit --rule PREFIX that matches no rule (exit 1).

misfire sorts every rule into one of five categories — convertible, safety_keep, judgment_keep, output_shape, non_directive — and recommends along a three-tier ladder:

• KEEP — judgment, safety, output-shape, and non-directive rules stay as prose.
• ELEVATE — move a rule into a path-scoped .claude/rules/*.md with paths: frontmatter to cut token rent.
• ENFORCE — scaffold a hook, but only for the violated convertible subset.

Install

misfire is stdlib-only with zero runtime dependencies and supports Python 3.9+.

pip install misfire
# or, with uv:
uv pip install misfire

A Homebrew tap is planned — brew install ek33450505/misfire/misfire will work once the homebrew-misfire tap is published.

From source (for development)