readme-diagram-auditlisted

# README Diagram Audit ## Overview Audit a repo's `docs/diagrams/` folder for convention compliance and coverage. For each file: validate frontmatter; check the taxonomy value is recognised; ensure exactly one code block exists. Flag missing diagrams the repo would benefit from (architecture, deployment, etc.) based on repo content. ## Steps ### Step 1 — Confirm the folder exists ```bash ls <repo>/docs/diagrams/ ``` If missing: offer to create it via the `docs-scaffold` skill in audit mode. ### Step 2 — Validate every diagram file For each `<repo>/docs/diagrams/*.md` not prefixed with `_`: | Check | Pass if | |---|---| | Has YAML frontmatter | First non-blank line is `---` | | `title` field present | Non-empty string | | `type` field present | In the recognised taxonomy, or accepted as an extension (warn but pass) | | `format` field present | One of `mermaid`, `png`, `svg`, `excalidraw` | | Exactly one code block | `grep -c '^```' file` returns exactly 2 | The fastest way to run this: `python <repo>/scripts/embed_diagrams.py --check` covers most of it and additionally verifies all embedded copies are in sync. ### Step 3 — Assess coverage Based on repo content, flag missing diagram types: | Repo signal | Suggested diagram type | |---|---| | Has a CI/CD workflow or deploy pipeline | `deployment` | | Has a cluster / multi-host topology | `infra-topology` | | Has a request lifecycle, auth handshake, or hook flow | `sequence` | | Has a domain entity with status transi