| name | audit-phase-docs |
| description | Audits Meridian phase docs against each other and the codebase; reports gaps and optionally applies draft improvements. Use with /audit-docs for brownfield or Meridian-started projects. |
| allowed-tools | Read, Glob, Grep, Bash, Edit, Write |
Audit phase docs (Meridian)
Read-only by default. With manager approval in the same turn, apply draft fixes only — never approved.
Selective reading
| File | When to read |
|---|
.agent/references/templates/phase-docs/{doc}.md | Mandatory — read full guide (what/for/how/revisit) + compare product docs/ to stub |
.agent/skills/init-project/references/doc-templates.md | Global rules |
All docs/0X_*.md present | Mandatory |
docs/inventory/as-is.md | If exists |
docs/05_architecture.md + docs/architecture/ | Consistency |
| Codebase (sample) | Spot-check claims in docs |
When to trigger
- Phase docs feel thin after
/init-meridian or /document-project
- Docs may have drifted from code
- Before approving
05_architecture or starting epics
- Workflow
/audit-docs
- Manager: “audit docs”, “refine scope”, “review governance”, “improve phase docs”
Not for US — use /review-us. Not for product brief — use /discover.
Audit dimensions
| # | Dimension | Check |
|---|
| 1 | Guide compliance | Product doc matches template guide: sections filled, no silent TBD |
| 2 | Depth checklist | Template depth checklist + empty ## |
| 3 | Dependency order | depends_on / blocks frontmatter |
| 4 | Cross-doc | Scope users ↔ 03; stack ↔ 01; layers 04 ↔ 05 |
| 5 | Evidence | Mode B claims have paths; stale paths flagged |
| 6 | Gates | 05 not approved while 04 empty; security gaps |
| 7 | Inventory | High rows promoted or explained in scope/architecture |
Procedure
- List all phase docs + frontmatter status.
- Score each doc:
ok | thin | missing | stale | contradiction.
- Spot-check codebase for top 5 risks (auth, data store, main app entry).
- Write audit report in chat (table + prioritized fixes).
- If manager asked to fix or
$ARGUMENTS contains apply:
- Edit only
draft or review docs
- Never set
approved
- Never create US/epics
- If apply changed scope, stack, security, or architecture narrative → mandatory
/update-decisions-log (prepend-decision) before reporting done; cite affected docs in --impact.
Output format
Phase docs audit:
Package root:
Docs scanned: N
Summary: ok X | thin Y | issues Z
| Doc | Score | Top issue |
| --- | ----- | --------- |
Cross-doc contradictions:
Code vs doc mismatches:
Priority fixes (ordered):
Applied draft fixes: yes | no — [paths]
Next: /document-project | /architecture | /security-pass | human approve 04
vs other commands
| Command | Focus |
|---|
/audit-docs | All phase docs + consistency |
/document-project | Create/refresh from codebase |
/discover | Product intent brief |
/review-us | Single US row only |
