Finding

spec/00-introduction.md §0.5.1 says every diagnostic MUST include description, rationale, fix, and spec_ref. Live state at HEAD 08c1197:

Of the 76 partially-tagged sites, 75 are missing fix=, 44 are missing rationale=, 44 are missing spec_ref=.

This shows up in real output. Example: E140 (operator type mismatch on numeric operands) produces description + rationale + spec_ref but no Fix: paragraph — exactly the kind of error where a Fix (showing a conversion or a type-correcting move) is the cheapest possible signal for the model.

$ vera check wrong_type.vera
[E140] Error at wrong_type.vera, line 4, column 3:
      @Bool.0 + @Int.0
      ^

  Operator '+' requires numeric operands, found Bool and Int.

  Arithmetic operators work on Int, Nat, or Float64.

  See: Chapter 4, Section 4.3 "Operators"

No Fix: paragraph. Compare with E001 / E122 / E130 / E500, all of which are fully curated.

Suggested fix — mechanical, two-pass

Pass 1: enforcement going forward

Add a pre-commit hook (extending the scripts/check_walker_coverage.py pattern) that parses every Diagnostic(...) constructor and every self._error(...) / self._warning(...) call in vera/, and fails if any of them is missing rationale=, fix=, or spec_ref=.

Defensive / internal-only errors (e.g. Unknown expression type in expressions.py fallback branches) can opt out per-call with # noqa: diag-fields comment carrying an inlined reason — mirroring how the walker-coverage check handles its categories.

Pass 2: backfill the existing 76 partial sites

Once the hook exists, run a one-pass cleanup across checker, verifier, and codegen call sites to populate the missing fields. Error codes are stable; spec sections are stable; Fix patterns follow predictable categories. Single PR of mostly-mechanical work, possibly split by phase (parse / type / verify).

Acceptance criteria

1. New script scripts/check_diagnostic_fields.py parses every Diagnostic(...) constructor and _error() / _warning() call in vera/ and fails when any of rationale= / fix= / spec_ref= is missing without an opt-out marker
2. Hook runs in CI on every PR + pre-commit
3. Opt-out is per-call with # noqa: diag-fields and the reason must be inlined as a sibling comment
4. All existing _error / _warning call sites in vera/checker/, vera/verifier.py, and vera/codegen/ either populate all three fields or carry an opt-out marker with rationale
5. vera check wrong_type.vera (where wrong_type.vera mixes @Bool.0 + @Int.0) produces a Fix: paragraph

Estimated effort

A day for the hook + audit script. 2–3 days for the backfill PR, splittable into smaller phase-scoped PRs.

Related

• Walker-completeness audit: every isinstance(expr, ast.X) dispatch chain enumerates all Expr subclasses #597 (walker-completeness enforcement) — the template for the hook approach. Same shape: # WALKER_COVERAGE: checklist comments, enforced by a script in scripts/, integrated into pre-commit + CI.

Origin

Surfaced by a strategic compiler review on 2026-05-18 (v0.0.155). Marked P1 (quality, load-bearing claim — "diagnostics as instructions" is a core differentiator). All counts independently verified before filing.