Judgment audit — the discipline beyond lint
Parent: structure
The split: lint / type / test guard mechanical correctness (mechanical-guardrails); the audit guide guards judgment quality — "mechanical correctness ≠ clean architecture." A self-evolving doc; the first audit pass produced findings 1–9 and a refactor.
Process: (1) read intent before implementation (guess behavior from names / signatures first); (2) walk ONE real end-to-end path — debt hides in cross-module seams, not units; (3) reverse-walk the error paths (is the error swallowed? can the caller distinguish "no data" from "crashed"?); (4) score against the 10 dimensions, logging file:line + severity (blocker / debt / style) + one line; (5) output an audit table — do NOT fix inline.
The 10 dimensions (compressed):
- if-density vs intent;
- fail loud vs silent (legal silent-degrade needs ALL THREE: expected business state + explicit semantics / comment / test + doesn't mask a real fault);
- single source of truth (derived data isn't stored);
- pragmatic SOLID;
- patterns only on the cutting edge (single-method interface → func type);
- naming == behavior (the repo's own example:
seoactually meant landing / reader); - state / invariant / concurrency (invariants guarded by data constraints, not call order; a flaky test is a design smell);
- boundary / leak (the one-line test: delete the concrete plugin — does the base still compile?);
- error shape (sentinel / typed);
- test honesty (assert correctness, not "didn't crash"; catch false-greens that silently ran a fallback).
Note the resonance: this is a gate on judgment quality — the harness-theory reading is that audit-guide supplies the semantic-gate rubric that lint can't mechanize (mechanical-guardrails holds the α≈0 tier; this holds the calibrated-judgment tier).