optimize agent-docs

skills/agent-docs/references/severity-model.md

@@ -0,0 +1,38 @@
+# 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.
+
+## Typical Mapping
+
+- `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
+
+## Reporting Rule
+
+- 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.