/context-audit

name: context-audit
version: 1.0.0
description: |
  Token-hygiene audit of the always-loaded context stack — CLAUDE.md,
  AGENTS.md, auto-memory MEMORY.md, and the bootstrap-rendered identity files
  (SOUL.md, USER.md, ACCESS_POLICY.md, HEARTBEAT.md) or their harness
  equivalents. Finds redundancy, contradictions, stale content, compression
  candidates, and skill-extraction candidates; produces a ranked action list
  sorted by token savings with a risk class per finding. REPORT-ONLY: this
  skill never edits any audited file. Recommendations for bootstrap-rendered
  files target the interview answer bank / templates, never the rendered
  output. Judging routes through `gbrain eval cross-modal` (single cheap
  model by default; full multi-model panel is explicit opt-in).
triggers:
  - "context audit"
  - "context diet"
  - "system prompt audit"
  - "prompt compression"
  - "reduce context size"
  - "audit my context stack"
  - "context is too big"
  - "token hygiene"
tools:
  - shell
  - read
mutating: false
writes_pages: false
upstream: context-audit@fc834ee

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

> **Convention:** see [conventions/brain-first.md](../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](../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:

| File | Role | Fix belongs in | |---|---|---| | project `CLAUDE.md` / `AGENTS.md` | orientation, routing, invariants | the file itself (source-editable) | | user-global `CLAUDE.md` | cross-project instructions | the file itself (source-editable) | | auto-memory `MEMORY.md` | promoted memory blocks | the memory store (demote/expire) | | `SOUL.md`, `USER.md`, `ACCESS_POLICY.md`, `HEARTBEAT.md`, rendered `AGENTS.md` | bootstrap-rendered identity files | the interview answer bank / templates — NEVER the rendered file | | harness system-prompt fragments (identity/tools files) | per-harness | wherever that harness sources them |

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](../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 w