audit

name	audit
argument-hint	[--deep] [--drift] [category, tag, or scope]
description	Audit Archcore docs: dashboard (counts, status, relations, orphans), deep coverage audit, or drift detection (code/cascade/temporal staleness). Use for 'show status', 'documentation gaps', 'check if docs match code', or after a staleness warning. Not for creating docs.

/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).

Global sources (only when present). If any list_documents result has global: true / read_only: true / source_kind: "global", load skills/_shared/globals.md. Exclude global documents from every local-health metric — category / status / type counts, orphan detection (globals carry no local relations by design), tag hygiene, coverage gaps, and drift — mirroring archcore status, which scopes these checks to local documents only. Globals are read-only org-wide context, not this project's documents; counting them inflates totals and reports them as false orphans. You MAY add one separate line naming the mounted source(s) and their count (e.g. Global sources: company (11 docs, read-only)). If no result is global, audit exactly as below — no change.

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:

1. Overview — totals by category and status
2. Gaps — missing documents or relations with specific recommendations
3. Staleness — documents needing attention
4. Orphans — documents with no relations
5. 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.