39 lines
1.8 KiB
Markdown
39 lines
1.8 KiB
Markdown
# 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.
|