Autofix in the hook, don't just flag

This is a principle

A reusable technical claim: something I would want true in any of my work.

Claim. Where a tool can safely auto-correct an issue, have it fix the file in place rather than merely reporting it for a human to fix manually.

When to apply. Deterministic, safe transforms (formatting, import sorting, trailing-whitespace, canonical JSON, line endings). Not for changes needing judgement (logic fixes, ambiguous lint rules) - those should flag, not auto-edit.

Why. A tool that only reports "line 40 has trailing whitespace" spends human attention on mechanical toil and creates a nag-loop: run, read, hand-fix, re-run. If the fix is deterministic, the machine should just apply it, leaving humans to review a clean result. This shrinks review noise and makes the canonical form the path of least resistance instead of a chore.

Snippet.

- id: markdownlint-cli2
  args: [--config=.markdownlint-cli2.jsonc, --fix]   # fix, don't just report
- id: ruff-format
- id: pretty-format-json
  args: [--autofix]

How enforced. Prefer formatters and --fix/--autofix modes in the hook chain. Order matters when several fixers touch the same files - see Order auto-fixers so later ones do not re-dirty earlier output.

Backlinks

The following pages link to this page:

• Order auto-fixers so later ones do not re-dirty earlier output
• Principles
• Spell-checking prose in a pre-commit hook: corpus checkers, dictionary checkers, and what each one misses
• skills.sh: repository layout, selective install and telemetry