---
name: findings-schema
description: The exact JSON output shape pragent must emit at the end of a review. Load this before producing findings.
---

# pragent findings schema

The review's FINAL message is a short prose summary followed by ONE fenced
```json code block. The Python shell parses the LAST ```json fenced block in the
message — so the JSON must be the last thing, and it must be valid.

## Shape

```json
{
  "summary": "One-paragraph overview of the change and its risk, plus severity counts.",
  "findings": [
    {
      "severity": "critical|high|medium|low",
      "path": "path exactly as it appears in the diff's `+++ b/` side",
      "line": 12,
      "problem": "one line: what is wrong",
      "fix": "one line: how to fix it",
      "suggestion": "exact replacement lines, indented as in the file, or \"\"",
      "reference": "https://... or \"\""
    }
  ]
}
```

## Field rules

- `severity` — one of `critical`, `high`, `medium`, `low`. Anything else is
  coerced to `medium` by the parser.
- `path` — the post-change path, exactly as in the diff (`+++ b/foo/bar.ts`
  → `foo/bar.ts`). Required; a finding without a real path is dropped.
- `line` — a post-change line number (int ≥ 1) that exists in `path` after the
  PR. Required; bad/missing line → the finding becomes a summary bullet instead
  of an inline comment.
- `problem` — one line, concrete: what is wrong and why it matters.
- `fix` — one line, the remedy. Empty string if the fix is architectural.
- `suggestion` — the literal new code replacing the flagged line(s). Minimal,
  just the changed lines, indented as they appear in the file. **Empty string**
  when no safe textual replacement exists (missing test, architectural note, a
  fix that needs context beyond one hunk). The pilot wraps this in a fenced code
  block tagged with the file's language so Gitea syntax-highlights it. (Gitea
  1.26.x has no GitHub-style "Apply suggestion" button, so a ```suggestion fence
  is not used — a language-tagged fence gives highlighting and loses nothing.)
- `reference` — a URL (CVE, library docs, spec) backing the finding, or `""`.
  Only link authoritative sources; don't fabricate URLs.

## Clean diff

If there's nothing to report: `{"summary":"<what it does, why it's fine>","findings":[]}`.

## Don't

- No prose after the closing ``` of the JSON block.
- No extra keys — unknown keys are ignored by the parser, so don't rely on them.
- Don't repeat findings from `prior_reviews`.