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