optimize agent-docs

skills/agent-docs-repo-alignment/SKILL.md

@@ -20,19 +20,24 @@ Use this skill to compare AGENTS and `agent-docs` against the real repository. I
 
 1. Read the docs in scope.
 2. Read `../agent-docs/references/repo-alignment-checklist.md`.
-3. Inspect the repository facts relevant to the claim:
+3. Read `../agent-docs/references/severity-model.md`.
+4. Read `../agent-docs/references/report-format.md`.
+5. Inspect the repository facts relevant to the claim:
    - scripts and `package.json`
    - ports and proxy config
    - directory and package structure
    - shared contracts and DTO ownership
    - tests or verification commands
    - runtime and thread-sync code paths when relevant
-4. Record observed facts first.
-5. Compare doc claims against repo facts.
-6. Report:
-   - confirmed matches
-   - must-fix drift
-   - wording drift or ambiguity
+6. Record observed facts first.
+7. Compare doc claims against repo facts.
+8. For each finding or confirmation, report it in this order:
+   - doc claim
+   - observed repo fact
+   - result: `confirmed` / `must-fix drift` / `wording drift`
+   - severity when the item is not `confirmed`
+9. Use the repo-alignment shape from `report-format.md`.
+10. Keep `must-fix drift` for statements that currently misstate repository facts, commands, ownership, or behavior. Use `wording drift` for stale or imprecise wording that should still be cleaned up.
 
 ## Boundary
 

skills/agent-docs-repo-alignment/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Check agent-doc repo alignment"
   short_description: "Compare agent-docs against repo facts"
-  default_prompt: "Use $agent-docs-repo-alignment to compare AGENTS.md and agent-docs against the repository facts: code, scripts, structure, and configuration."
+  default_prompt: "Use $agent-docs-repo-alignment to compare AGENTS.md and agent-docs against current code, scripts, structure, and config, report claim plus fact plus result, label drift by severity, and note when refactor is required."