Design Spec: /atlas-audit

Date: 2026-04-15

Status: Draft

Owner: Atlas

Purpose

A single comprehensive skill that audits, measures, restructures, and monitors fleet operational efficiency. This is Atlas's prime directive skill — "how efficient are our fleet ops" expressed as a runnable tool.

The skill produces metrics (writes to SSOT tables), makes structural improvements (rewrites CLAUDE.md, compresses rules, deduplicates memory), and establishes baselines for ongoing monitoring. It replaces /context-diet, /reconcile, and /manifest refresh as the one maintenance skill.

Prerequisites

1. SSOT Guide (`docs/ssot/GUIDE.md`)

Must exist before the skill can make decisions. Defines:

Fact vs Statement classification (fleet_rules s6#8): If a wrong value causes an agent to do the wrong thing, it is a fact (goes in fleet table). If it is context or rationale, it is a statement (goes in Aion wiki).
Three trust levels for facts: unverified (extracted from docs, needs checking), verified (confirmed by domain owner or live system), statement (narrative context, loose verification).
Four SSOT layers: Storage (fleet tables + Aion wiki), Injection (fleet-rules-inject.sh at launch), Retrieval (CLI-first, MCP-fallback), Recording (agents write new facts back).
CLI-first tool protocol: CLI tools are the primary interface for fleet operations. MCP tools are fallback only, used when Bash is unavailable. For every MCP server, a CLI equivalent must exist and be the documented first-choice path.

2. Metrics Tables (Pantheon Supabase)

The skill writes measurements to these tables. Designed by Proteus, owned by Atlas.

`fleet_context_metrics`

Per-repo context efficiency measurements.

Column	Type	Description
id	uuid	PK
repo	text	FK to fleet_repositories.name
measured_at	timestamptz	When this measurement was taken
measured_by	text	Session/agent that took the measurement
claude_md_chars	int	CLAUDE.md character count
repo_rules_chars	int	.claude/rules/ total chars
global_rules_chars	int	~/.claude/rules/ total chars
memory_index_chars	int	MEMORY.md index chars
memory_files_chars	int	Total memory topic file chars
memory_file_count	int	Number of memory topic files
skills_count	int	Number of skills in .claude/skills/
skills_frontmatter_chars	int	Total skill frontmatter chars (system prompt cost)
agents_count	int	Number of agent definitions
agents_chars	int	Total agent definition chars
always_loaded_total	int	Sum of all always-loaded content chars
est_tokens	int	always_loaded_total / 4 (rough estimate)
context_files_chars	int	On-demand context/ directory total chars
audit_type	text	'full' or 'monitor'

`fleet_ssot_compliance`

Per-repo SSOT alignment scores.

Column	Type	Description
id	uuid	PK
repo	text	FK to fleet_repositories.name
measured_at	timestamptz
hardcoded_facts	int	Facts found in markdown that should be in fleet tables
ssot_references	int	Lines that correctly reference SSOT (fleet CLI, queries)
duplicate_rules	int	Rules loaded multiple times (global + repo + memory overlap)
stale_memory_files	int	Memory files whose content is now in code/git/tables
unverified_facts	int	Facts in fleet tables with unverified trust level
compliance_score	numeric	0-100, weighted composite

`fleet_tool_efficiency`

Session-level tool usage patterns (populated by Argus or session-end hooks).

Column	Type	Description
id	uuid	PK
repo	text
session_id	text
measured_at	timestamptz
cli_lookups	int	fleet/fleet-path calls via Bash
mcp_lookups	int	MCP tool calls for SSOT data
toolsearch_calls	int	ToolSearch invocations (overhead indicator)
total_tool_calls	int	All tool calls in session
transcript_chars	int	Total session transcript size
cli_first_ratio	numeric	cli_lookups / (cli_lookups + mcp_lookups)

Operational Model

Full Audit

Run once per repo. Heavy. Produces baseline, makes structural changes.


/atlas-audit <repo-path>
/atlas-audit ~/Dev/_K4120S/constellation-hades

Monitor Check

Lightweight. Measures current state, compares to baseline, flags drift.


/atlas-audit monitor <repo-path>
/atlas-audit monitor --fleet       # all repos

Re-audit Trigger

When a repo's metrics fall behind the fleet average (detected by Argus or the monitor check), a full audit is triggered. The operator decides — Atlas does not auto-audit.

Full Audit Protocol

Phase 1: Measure (read-only)

Baseline everything. Write measurements to fleet_context_metrics.

Always-loaded content: CLAUDE.md + repo rules + global rules + MEMORY.md + memory topic files
On-demand content: context/ directory, skills (frontmatter only), agent definitions
SSOT compliance scan:

Grep CLAUDE.md for hardcoded infrastructure identifiers (Supabase project IDs, URLs, port numbers, filesystem paths)
Grep for content that duplicates global rules or fleet_rules
Grep memory files for content that's now in committed code or fleet tables
Count lines that correctly reference SSOT (fleet commands, table queries)

Fact/statement classification: For each finding, classify using s6#8 — is this a fact (would cause wrong agent behavior if wrong) or a statement (context/rationale)?

Output: Baseline report with current numbers.

Phase 2: Plan (operator review)

Present findings organized by impact. No changes yet.

For each finding:


FINDING: {description}
Type: fact | statement | duplicate | stale
Location: {file}:{line range}
Impact: {chars saved if fixed}
Action: {move to fleet table | move to Aion | delete | compress | reference SSOT}

Group by action type. Show total projected savings.

The operator approves, modifies, or rejects the plan.

Phase 3: Execute (structural changes)

Apply approved changes:

Facts in markdown → Verify the fact exists in a fleet table. If it does, replace the markdown with a fleet CLI reference. If it doesn't, INSERT the fact (unverified) and replace the markdown.
Statements in CLAUDE.md → Move to Aion wiki via aion_capture or to context/ as a deferrable reference file.
Duplicate rules → Remove the duplicate, keep the highest-authority source (fleet_rules > global rules > repo rules > memory).
Stale memory → Archive (never delete without operator confirmation).
Bloated sections → Compress. Verbose violation rules become table rows. Repo maps stay (structural, needed for navigation).
Missing SSOT references → Add fleet CLI commands where agents need to look up facts.

Phase 4: Verify

Re-measure everything. Write post-audit measurements to fleet_context_metrics with audit_type = 'full'. Compute delta:


## Audit Complete

Before: {N} chars ({T} est. tokens) always-loaded
After:  {N2} chars ({T2} est. tokens) always-loaded
Saved:  {delta} chars ({pct}% reduction)

SSOT compliance: {before_score} → {after_score}
Hardcoded facts: {before} → {after}
Duplicate rules: {before} → {after}

Write compliance score to fleet_ssot_compliance.

Monitor Protocol

Lightweight check. No structural changes. Runs in < 30 seconds.

Measure always-loaded chars for target repo(s)
Compare to most recent fleet_context_metrics row for that repo
If delta > 10% growth since last audit: flag for re-audit
If any new hardcoded facts detected: flag
Write monitor measurement to fleet_context_metrics with audit_type = 'monitor'

For fleet-wide monitor:

Rank all repos by always-loaded chars
Flag any repo > 1 standard deviation above fleet mean
Output a fleet efficiency summary table

Atlas KPIs (displayed on Atlas UI page)

These are the metrics the Atlas page in the Pantheon web app will show:

Context Efficiency

Always-loaded tokens per repo (bar chart, ranked)
Fleet average vs individual repo
Trend over time (per audit/monitor cycle)
Global rules overhead as % of total

SSOT Compliance

Compliance score per repo (0-100)
Hardcoded facts remaining (should trend to 0)
Unverified facts in fleet tables (backlog indicator)
Fact vs statement ratio in fleet_rules

Tool Call Efficiency

CLI-first ratio per repo (target: >95%)
ToolSearch calls per session (overhead indicator)
MCP usage where CLI exists (violations)
Avg tokens per SSOT lookup

Session Cost

Tokens per session by project (when API metering is available)
Transcript sizes (proxy for session cost)
Sessions per project per week
Subagent spawn ratio

Skill & Rule Health

Skills per repo, Arsenal symlink integrity
fleet_rules coverage (sections populated vs empty)
Argus violation trend (should decrease over time)
Rule injection health (fleet-rules-inject.sh success rate)

Integration Points

System	How atlas-audit connects
Argus	Monitor check can be added as an Argus probe (P-level). Argus flags repos that drift.
fleet_rules	Audit reads rules to understand what should be in tables vs markdown. Writes new facts found during audit.
Aion	Statements found in markdown are captured to Aion wiki. Decision rationale from the audit itself is captured.
Arsenal	Audit checks skill symlink health. Reports broken or missing distributions.
Atlas UI	UI reads fleet_context_metrics, fleet_ssot_compliance, fleet_tool_efficiency tables.
fleet CLI	Audit uses `fleet` commands for all SSOT lookups (CLI-first).
/start	Session start can include a quick monitor check if the repo hasn't been measured in N days.

What This Replaces

Old Skill	What atlas-audit absorbs
`/context-diet`	Phase 3 pruning (but SSOT-aware, not just size-based)
`/reconcile`	Phase 1 SSOT compliance scan (but with metrics, not just drift detection)
`/manifest refresh`	Phase 1 structural measurement (but writes to fleet tables, not markdown)
`/domain-architect`	Phase 3 restructuring (but driven by measurements, not ad-hoc)

The old skills can remain as lightweight aliases or be deprecated. atlas-audit is the comprehensive version.

Design Decisions

Decision	Choice	Rationale
Ownership	Atlas only	One authoritative voice prevents conflicting self-optimization across agents
CLI-first for all SSOT access	`fleet` CLI, not MCP	~7x more token-efficient, 1 tool call vs 2+, compact output
Fact/statement classification	fleet_rules s6#8	Operator-defined: "if wrong value causes wrong agent behavior, it's a fact"
Metrics in Supabase tables	fleet_context_metrics, fleet_ssot_compliance, fleet_tool_efficiency	SSOT principle: metrics are facts about the fleet, they go in tables
Operator approval before changes	Phase 2 plan review	Structural changes to agent harnesses are high-impact, not automated
Monitor as separate mode	Lightweight, no changes	Full audit is expensive; monitoring should be cheap enough for Argus
Archive, never delete	Memory and stale content moves to archive dirs	Reversibility; operator can review archived content

Open Questions

Argus probe integration: Should the monitor check become an official Argus probe (e.g., P24)? This would make it automated on the 6-hour Argus cycle.

Session cost metering: stats-cache.json is 33 days stale. No API token metering exists. The tool efficiency table can only be populated if we build a metering layer or scrape the Anthropic Console. What's the path here?

fleet_tool_efficiency population: This table requires parsing session transcripts for tool call patterns. Should this be a session-end hook, an Argus probe, or part of the JSONL parsing pipeline that Mnemosyne is designing?

Old skill deprecation: Should /context-diet, /reconcile, /manifest refresh be removed from Arsenal distribution, or kept as lightweight shortcuts that call into atlas-audit phases?

Cross-repo execution: atlas-audit targets other repos. Should it read their files directly (simple, but crosses domain boundaries), or dispatch measurements to the owning agent and collect results?