Design Spec: /atlas-audit

Date: 2026-04-15 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.

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
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
- 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

Phase 2: Plan (operator review)

Present findings organized by impact. No changes yet.

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 fact exists in fleet table. If yes, replace markdown with fleet CLI reference. If no, INSERT as unverified and replace.
Statements in CLAUDE.md → Move to Aion wiki via aion_capture or to context/ as deferrable reference.
Duplicate rules → Remove duplicate, keep 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.
Missing SSOT references → Add fleet CLI commands where agents need to look up facts.

Phase 4: Verify

Re-measure everything. Write post-audit measurements. Compute delta:

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}

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
If delta > 10% growth since last audit: flag for re-audit
If any new hardcoded facts detected: flag
Write monitor measurement with audit_type = 'monitor'

Atlas KPIs

Displayed on the Atlas page in the Pantheon web app.

Context Efficiency

Always-loaded tokens per repo (ranked)
Fleet average vs individual repo
Trend over time
Global rules overhead as % of total

SSOT Compliance

Compliance score per repo (0-100)
Hardcoded facts remaining (→ 0)
Unverified facts backlog
Fact vs statement ratio

Tool Call Efficiency

CLI-first ratio (target: >95%)
ToolSearch overhead per session
MCP violations (CLI exists but MCP used)
Avg tokens per SSOT lookup

Session Cost

Tokens per session by project
Transcript sizes (cost proxy)
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 as Argus probe. Argus flags repos that drift.
fleet_rules	Reads rules to classify facts vs statements. Writes newly discovered facts.
Aion	Statements found in markdown captured to wiki. Audit rationale captured.
Arsenal	Checks skill symlink health. Reports broken distributions.
Atlas UI	UI reads fleet_context_metrics, fleet_ssot_compliance, fleet_tool_efficiency.
fleet CLI	All SSOT lookups use `fleet` commands (CLI-first).
/start	Session start includes quick monitor check if 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 (with metrics, not just drift detection)
`/manifest refresh`	Phase 1 structural measurement (writes to fleet tables, not markdown)
`/domain-architect`	Phase 3 restructuring (driven by measurements, not ad-hoc)

Design Decisions

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

Open Questions

1. 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.

2. 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?

3. 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?

4. 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?

5. 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?

Generated by Atlas · constellation-atlas · War Room Session 2026-04-15