optimize agent-docs

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

@@ -0,0 +1,47 @@
+# 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.