Why a Good Linter's Quality Depends on What It Chooses Not to Flag

A developer building a configuration directory checker found that the hardest design decisions involved choosing which rules to leave out, not which to include. The core principle adopted was simple: only flag issues that official documentation explicitly identifies as errors or warnings, with no rule added without a citable source URL. Every finding in the tool's output includes a mandatory 'because' field containing a documentation link, enforced at both the type level and in automated tests. The developer deliberately skipped checks for things like JSON schema validation and path-anchoring logic where confidence was low, reasoning that false positives erode user trust faster than missed detections. The tool uses only two severity levels — error and warn — avoiding an 'info' tier that tends to become a dumping ground for uncertain, low-value noise.