/archcore:audit

Audit Archcore documentation. Three modes, picked from arguments:

short (default) — compact dashboard: counts, statuses, relations, orphans
deep (--deep or any non-flag arg) — coverage gaps, staleness, relation health, prioritized recommendations
drift (--drift) — code/cascade/temporal drift detection with assisted fix

When to use

"Show status" / "How many docs do we have?" / "Dashboard" → short mode
"Audit the knowledge base" / "Documentation gaps?" → --deep
"Are any docs out of date?" / "Check if documentation matches the code" → --drift
Session-start staleness warning appeared → --drift

Not audit:

Creating new documentation → /archcore:capture, /archcore:plan, /archcore:decide
Reading applicable rules/ADRs/specs before coding → /archcore:context
Picking up where work left off → /archcore:context

Routing table

Signal	Mode	Scope
No arguments	→ short dashboard	All documents
`--deep`	→ deep audit	All documents
`--deep <filter>` or `<filter>` (non-flag arg)	→ deep audit, filtered	Filter applied
`--drift`	→ drift detection	All documents
`--drift <filter>`	→ drift detection, filtered	Filter applied

The short dashboard is project-wide by design — it doesn't take filters. Any non-flag argument without --drift implies deep audit on a filter.

Execution

Step 1: Gather data

Call in parallel: mcp__archcore__list_documents and mcp__archcore__list_relations. Apply filter from $ARGUMENTS if present (tag, category, or type).

Short mode (default): present dashboard

Output four tables, then a one-line issues summary. Data only, no analysis.

Documents by Category

Category	Count
Vision	n
Knowledge	n
Experience	n
Total	n

Documents by Status

Status	Count
draft	n
accepted	n
rejected	n

Documents by Type — list each type with count, skip types with 0.

Relations

Type	Count
related	n
implements	n
extends	n
depends_on	n

Issues — orphaned documents (no relations), high draft count. One line each, no explanations.

End with: For a full audit with recommendations, run /archcore:audit --deep. For staleness detection, run /archcore:audit --drift.

Deep mode (`--deep` or any non-flag arg): analyze and report

Check for:

Coverage gaps:

ADRs without rules/guides (decisions not codified)
PRDs without plans (requirements without implementation path)
Rules without guides (standards without instructions)
Empty categories or types with zero documents

Staleness:

Documents stuck in draft that may need accepted or rejected
Documents with stale content indicators

Relation health:

Orphaned documents (no incoming or outgoing relations)
Plans without implements to a PRD
Specs without implements to requirements
Broken chains (ISO cascade with gaps)

Tag hygiene:

Tags used only once (potential inconsistency)
Related documents with different tags

Report with these sections:

Overview — totals by category and status
Gaps — missing documents or relations with specific recommendations
Staleness — documents needing attention
Orphans — documents with no relations
Actions — prioritized list of fixes, most impactful first

Drift mode (`--drift`): code/cascade/temporal staleness

Read skills/audit/lib/drift-detection.md for the detailed staleness-detection protocol. It covers:

Code-drift — cross-references document content against git changes; flags docs whose referenced source paths changed since the doc was last updated.
Cascade — uses the relation graph to find sources whose targets (implements/depends_on/extends) were updated after them.
Temporal — long-running drafts, accepted docs with TODO markers, rejected docs still referenced as active.
Assisted fix — interactive update flow per finding, one document at a time, always confirms before applying via mcp__archcore__update_document.

Result

Short mode: compact dashboard, data only.
Deep mode: actionable report with prioritized fixes — findings and recommendations only, no verbose analysis.
Drift mode: severity-grouped findings (critical / cascade / temporal) with optional interactive fixes via MCP. No modifications without user confirmation.