Severity

Home / Reference / Severity levels

Severity levels

CommitBrief findings are tagged with one of five severity levels. The LLM picks the level when emitting each finding (constrained by the structured-output schema for API providers; prompt-driven for the rest).

Ordering

Highest impact → lowest:

critical > high > medium > low > info

This ordering drives:

• --fail-on=<severity> — "fail at this level or worse".
• Cards renderer panel color (severity-coded left border).
• Compact mode ordering.

Level definitions

These come from the embedded COMMITBRIEF.md default. A custom rules file can redefine them; the literal level names are part of the public JSON schema and cannot be renamed.

critical

Exploitable defects, data-loss bugs, regulatory violations, hard security holes (auth bypass, injection, key leak). Treat as release-blocking.

high

Likely defects with significant impact: race conditions, missing authorization checks, broken business invariants, severe performance regressions. Should be fixed before merge.

medium

Real bugs with moderate impact or significant maintainability issues: incorrect-but-recoverable error handling, missing input validation that downstream catches, expensive but non-critical inefficiencies.

low

Minor defects or notable improvements that do not block the PR: inconsistent style breaking project conventions, small efficiency wins, missed cleanup.

info

Pure informational notes: educational pointers, alternative approaches, "consider this for v2." Not a defect.

Severity in the JSON schema

{
  "severity": "high"
}

String, lowercase, one of critical | high | medium | low | info. See JSON schema.

Severity in OUTPUT.md

The Go template gets .Severity as a render.Severity string type. To group by severity:

{{ $bucketed := groupBySeverity .Findings }}
{{ with index $bucketed "critical" }}
## Critical findings
{{ range . }}...{{ end }}
{{ end }}

See OUTPUT.md for the full template surface.

Severity in cards rendering

Each finding panel has a left border colored by severity:

Severity	Border color
critical	red
high	orange-yellow
medium	yellow
low	blue
info	gray

(Exact lipgloss colors live in internal/render/cards.go.)

Severity calibration

The embedded COMMITBRIEF.md default includes calibration guidance ("a missing nil check on user input that crashes the server is critical; a missing nil check on a debug-log field is low"). If you find the model over- or under-classifies, edit your project-local COMMITBRIEF.md to tighten the definitions for your context.

See also

• Exit codes — how --fail-on maps levels to pass/fail.
• JSON schema — the wire format.
• COMMITBRIEF.md — customising calibration.