# Report Format

Use these output shapes when reporting `agent-docs` findings. Keep the format compact, but preserve the field order so audits and follow-up refactors stay easy to compare.

## Audit Finding

```md
- <severity>: <short finding title>
  observed fact: <what was directly verified in the docs, references, or command output>
  inference: <why this creates adherence risk or maintenance risk>
  impact: <what the agent or maintainer is likely to get wrong>
```

## Consistency Finding

```md
- <severity>: <short finding title>
  structural evidence: <cycle, reachability gap, overlap signal, depth budget overrun, or secondary-router signal>
  refactor needed: <yes / no / maybe>
  note: <why the current structure is acceptable or why it should change>
```

## Repo-Alignment Finding

```md
- <result>: <short finding title>
  doc claim: <the wording from AGENTS.md or agent-docs>
  observed repo fact: <the file, command, or code area that confirms or contradicts the claim>
  severity: <omit when result is confirmed; otherwise blocking / major / minor / observation>
```

## Verification Summary

```md
- result level: <fully verified / structurally verified only / behavior check failed / verification incomplete>
  commands: <the commands run in the current turn>
  representative behavior checks: <performed / not performed / not required>
  unverified remainder: <anything still not checked>
  residual findings: <severity-labeled items that still remain after verification>
```

## Format Rules

- Keep findings first.
- Use the shared severity model when a severity is required.
- Keep `observed fact`, `structural evidence`, and `observed repo fact` grounded in files or command output from the current turn.
- Do not skip the required fields just because there is only one finding.