bluecraft/skills/agent-docs/references/report-format.md

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

- <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

- <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

- <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

- 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.