Context Audit

context-audit — Token Hygiene for the Always-Loaded Context Stack

Convention: see conventions/brain-first.md — before running a fresh audit, check the brain for prior audit reports (gbrain recall "context audit report") so you can compute token DRIFT since the last run and avoid re-flagging findings the user already declined.

Convention: see conventions/quality.md — every finding cites its file and evidence; no unsourced claims.

What this is

Every file that loads on every turn is a per-turn tax: tokens, latency, and — past a point — instruction-following quality. Always-loaded files accrete (append-only release notes, promoted memory blocks nobody re-reads, rules restated in three files that drift into contradiction). This skill audits the whole always-loaded stack at once and returns a ranked, evidence-cited action list sorted by token savings.

It is an auditor, not a surgeon. It measures, finds, ranks, and recommends. The user (or a skill the user explicitly invokes afterward) applies changes.

Scope: what counts as "always-loaded"

Enumerate what THIS harness actually loads every turn — do not assume a fixed list. Typical stack:

Skills, reference docs, and anything loaded on demand are OUT of scope as audit subjects — but they are the DESTINATION for skill-extraction findings (content that only matters for one workflow should move out of the always-loaded stack into a skill).

Contract

This skill guarantees:

• Report-only. No audited file is edited, no page is written, nothing is auto-fixed — including 🟢 zero-risk findings. The output is a recommendation list the user applies deliberately.
• Rendered-file safety. Any recommendation touching a bootstrap-rendered file is expressed as an answer-bank or template change (gbrain bootstrap interview --set KEY "..." then gbrain bootstrap render --only <FILE> --force), never as a direct edit. See skills/soul-audit/SKILL.md for the mechanics.
• Estimated with a stated basis, never invented. Token figures come from the deterministic pre-pass (wc -c bytes/2.8 — Claude-family tokenizers run ~2.6-3.5 bytes/token on markdown dense with paths and code spans; 2.8 is the calibrated midpoint of measured always-loaded markdown, see #4988). The report prints the divisor so a reader can re-derive every number. If the host client reports an exact per-category context breakdown (e.g. Claude Code /context), that figure outranks the estimate — quote it and use it for the stack total.
• Native judging. The draft report is quality-gated through gbrain eval cross-modal — no raw model API calls, no hardcoded model IDs.
• Cost line. Default judging is ONE cheap model (the user's utility-tier model, all three slots, --cycles 1 — a few cents). The full three-provider frontier panel runs only when the user explicitly asks for a "full" or "multi-model" audit (~3x+ the cost per cycle).

Procedure

1. Enumerate the stack (deterministic)

List the always-loaded files for this harness and measure each:

# bytes/2.8 (calibrated for Claude-family tokenizers on markdown, #4988); integer ceil: (n*10+27)/28
for f in CLAUDE.md AGENTS.md SOUL.md USER.md ACCESS_POLICY.md HEARTBEAT.md MEMORY.md; do
  [ -f "$f" ] && echo "$f: $(wc -c < "$f") bytes (~$(( ( $(wc -c < "$f") * 10 + 27 ) / 28 )) tokens)"
done

Record the total. If a prior audit report exists in the brain, compute drift (net tokens grown/shrunk since last run, which files moved).

2. Read and analyze (the agent does this — no model calls yet)

Read every file in the stack in full. Evaluate against six dimensions:

1. Token efficiency — tokens spent per unit of behavioral value
2. Redundancy — the same rule/fact stated in more than one file
3. Contradictions — conflicting rules, numbers, or policies across files
4. Skill-worthiness — content that only matters for a specific workflow (extraction candidate: move to a skill, load on demand)
5. Staleness — outdated facts, references to removed features, promoted memory blocks that no longer earn their slot
6. Clarity — instructions compressible without behavior change, or ambiguous enough to misfire

3. Classify every finding by risk

• 🟢 Zero risk — pure deletion of exact redundancy or dead content
• 🟡 Low risk — compression or skill extraction with a clear trigger
• 🔴 Medium risk — changes that could shift edge-case behavior

All three classes are recommendations. The risk class tells the user how much care to apply — it does not authorize this skill to act.

4. Judge the draft through the native eval runner

Write the draft report to a temp file, then gate it:

# Resolve the cheap judge from the user's model tiers — never hardcode an ID.
# (`gbrain models` shows all resolved tiers if the config key is unset.)
JUDGE=$(gbrain config get models.tier.utility)

gbrain eval cross-modal \
  --task "Context-stack token-hygiene audit: every finding cites file + quoted evidence; savings are estimated (bytes/2.8, divisor stated in the report), never invented; findings ranked by token savings; every rendered-file recommendation targets the interview answer bank or template, never a direct edit; risk class on every row" \
  --output /tmp/context-audit-draft.md \
  --slug context-audit-report \
  --cycles 1 \
  --slot-a-model "$JUDGE" --slot-b-model "$JUDGE" --slot-c-model "$JUDGE"

Full multi-model panel (explicit opt-in only — the user asked for a "full" / "multi-model" audit): omit the --slot-*-model overrides so the runner's native three-provider defaults apply.

Exit codes: 0 PASS — deliver. 1 FAIL — fix the flagged weaknesses in the draft (usually: an unquoted claim or a rendered-file edit recommendation) and re-judge. 2 INCONCLUSIVE (provider/key trouble) — deliver the report but label it "unjudged" prominently.