# content-hook-candidate Detect instructions that should be automated as hooks instead of prose instructions | | | |---|---| | **Severity** | info (auto) | | **Autofix** | - | | **Since** | v0.7.0 | | **Category** | [Content Intelligence](content-intelligence.md) | ## Why Prose instructions like "always run the formatter before committing" depend on the model choosing to follow them every time. Hooks execute deterministically on every matching event — they cannot be forgotten or deprioritized. Converting automatable instructions to hooks makes the behavior reliable instead of aspirational. ## Examples **Bad:** ```markdown Always run `prettier --write` after every change. Run tests before every commit. ``` **Good (hooks.json):** ```json { "hooks": { "PostToolUse": [ {"hooks": [{"type": "command", "command": "prettier --write ."}]} ] } } ``` ## How to fix Move the instruction into a hook configuration (`.claude/hooks.json` or equivalent). Use the hook type suggested in the violation message (e.g., `pre-commit`, `PostToolUse`, `Stop`). You can keep a brief note in the instruction file referencing the hook for documentation purposes. ## Configuration ```yaml rules: content-hook-candidate: enabled: auto # true | false | auto severity: info ``` ## Research Basis **Identifies instructions that should be automated as hooks** instead of prose instructions (e.g., "always run tests before committing"). Instructions like "run tests before every commit" are advisory — the model follows them probabilistically. A pre-commit hook runs deterministically, every time, without fail. When an instruction describes a mechanical, automatable action, it should be a hook. As one practitioner put it: *"The hook does not forget. It does not reason. It does not skip."* Instruction files should focus on judgment calls and context-dependent decisions that only the model can make. Automatable actions belong in hooks. **References:** - [Dotzlaw: Claude Code Hooks: The Deterministic Control Layer](https://www.dotzlaw.com/insights/claude-hooks/) — "Unlike CLAUDE.md instructions which are advisory, hooks are deterministic" - [Claude Code Security](https://docs.anthropic.com/en/docs/claude-code/security) — Hooks provide deterministic enforcement - [aitmpl.com: Block API Keys & Secrets from Your Commits with Claude Code Hooks](https://aitmpl.com/blog/security-hooks-secrets/) — "CLAUDE.md rules are suggestions. Hooks are enforcement." *Run `skillsaw explain content-hook-candidate` to see this documentation and the rule's effective configuration in your terminal.*