Severity Model

Use this model when reporting findings for agent-docs audits, consistency checks, repo-alignment reviews, or post-change verification.

Levels

blocking: the current document graph or wording is unsafe to follow. The agent is likely to route incorrectly, guess through ambiguity, or apply conflicting rules.
major: the docs are still usable, but the current state creates significant adherence risk, maintenance cost, or fact drift that should be fixed soon.
minor: the issue is real but localized. It does not usually break routing or authority outright, yet it increases noise, review cost, or future drift risk.
observation: useful context, tradeoff notes, or follow-up ideas that are not defects by themselves.

blocking
- duplicate authority with no explicit tie-break
- equally specific sibling docs that both explicitly apply
- unreachable active child doc
- stale references after a refactor
major
- high-noise secondary router behavior
- missing Authority or Classification Authority where required
- must-fix repo drift
- structure that exceeds routing-depth or out-degree budgets and now needs refactor
minor
- vague Applies To wording
- vague Authority wording that still has some usable anchor
- wording drift that does not yet misstate repository facts
- structure warnings that are notable but still acceptable for now
observation
- acceptable tradeoffs
- optional cleanup ideas
- residual risks after no concrete findings

Order findings by severity first, then by impact within the same severity.
Do not inflate style preferences into major or blocking.
If a finding could fit two levels, choose the higher one only when the current wording or structure is likely to cause a real routing, authority, or verification mistake.