# Context Audit

> Auditoría de higiene de tokens del stack siempre cargado (CLAUDE.md, AGENTS.md, MEMORY.md, SOUL.md, etc.): detecta redundancia, contradicciones y candidatos a compresión. Solo informa, nunca edita archivos.

Fuente: https://skillsagentes.com/skills/garrytan/gbrain/context-audit
Markdown: https://skillsagentes.com/skills/garrytan/gbrain/context-audit.md

Repositorio: https://github.com/garrytan/gbrain
Autor: garrytan
Licencia: MIT
Actualizado: hace 9 días
Coste de contexto: 179 tok instalada, 2.9k tok al activarse, 3.3k tok con todos los archivos del bundle
Bundle: 2 archivos, 13 KB
Permisos que pide: shell, read

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add garrytan/gbrain --skill context-audit --agent claude-code
# Cursor
npx -y skills add garrytan/gbrain --skill context-audit --agent cursor
# Codex
npx -y skills add garrytan/gbrain --skill context-audit --agent codex
# Gemini CLI
npx -y skills add garrytan/gbrain --skill context-audit --agent gemini
# Windsurf
npx -y skills add garrytan/gbrain --skill context-audit --agent windsurf
# Cline
npx -y skills add garrytan/gbrain --skill context-audit --agent cline
```

## Qué hace

- Mide en tokens todo el stack siempre cargado (CLAUDE.md, AGENTS.md, MEMORY.md, SOUL.md, etc.) con wc -c
- Detecta redundancia, contradicciones, contenido obsoleto y candidatos a extracción como skill
- Genera una lista de acciones priorizada por ahorro de tokens, con clase de riesgo por hallazgo
- Valida el borrador del informe vía `gbrain eval cross-modal` antes de entregarlo
- Nunca edita archivos: para archivos renderizados por bootstrap, apunta la recomendación al answer bank/plantilla

## Cuándo usarla

- Quieres auditar el contexto siempre cargado por tokens, latencia y calidad
- El usuario dice "context audit", "context diet" o "mi contexto es demasiado grande"
- Necesitas comparar el crecimiento de tokens desde una auditoría anterior (drift)

## Cuándo no

- Para auditar skills o docs de referencia cargados on-demand (no son objeto de esta auditoría)
- Para reescribir el contenido de identidad (usa soul-audit en su lugar)
- Para pedir una segunda opinión general sobre código u otro trabajo (usa cross-modal-review)

## Qué la activa

- "Haz un context audit de mi stack siempre cargado"
- "Mi contexto está demasiado grande, revisa qué se puede comprimir"
- "Audita CLAUDE.md, AGENTS.md y MEMORY.md por redundancia"
- "Quiero un context diet completo con panel multi-modelo"

## Antes de instalar

- Requiere el CLI `gbrain` (con `gbrain eval cross-modal` y tiers de modelo configurados) para el paso de juicio.
- Variables de entorno: JUDGE
- reads environment config

## Archivos

- SKILL.md — 11 KB
- routing-eval.jsonl — 2 KB

## SKILL.md

Reproducido tal cual desde garrytan/gbrain bajo MIT. Esta sección es el documento original y está en inglés.

# 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.
- **Measured, not guessed.** Token figures come from the deterministic
  pre-pass (`wc -c` / ~4 chars-per-token), never invented.
- **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:

```bash
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") chars (~$(( $(wc -c < "$f") / 4 )) 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:

```bash
# 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 measured (chars/4), not guessed; 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.

### 5. Deliver

Print the report in the conversation (see Output Format). If the user wants
it persisted, hand off to the brain-ops skill to file it under `openclaw/`
(agent-state notes) — this skill does not write pages itself.

Re-running after major edits to the stack, or on a schedule, is a
harness-routing convention the user can set up (see the cron-scheduler skill)
— nothing here runs automatically or guarantees a cadence.

## Output Format

```
# Context Audit — YYYY-MM-DD

Stack total: ~NN,NNN tokens across N files (drift since last audit: +/-N,NNN)
Findings: N (~NN,NNN tokens recoverable) | Contradictions: N
Judge verdict: PASS (single-model, utility tier) | receipt: <path>

| # | Save (tok) | Risk | File | Finding | Evidence | Recommended fix (and WHERE it lives) |
|---|-----------|------|------|---------|----------|--------------------------------------|
| 1 | ~2,400    | 🟢   | ...  | redundancy: X restated | "quoted line" | delete from A; canonical copy stays in B |
| 2 | ~1,100    | 🟡   | SOUL.md | stale: ... | "quoted line" | update answer bank key VOICE_REGISTER, re-render — NOT a SOUL.md edit |
...

## Contradictions (fix these first, savings aside)
- FILE-A says "..." but FILE-B says "..." — resolve toward <one>, delete the other.

## Skill-extraction candidates
- <content> only matters when <workflow> — extract via skill-creator, load on demand.
```

Sorted by token savings, descending — except contradictions, which are called
out first regardless of size (they cost correctness, not just tokens). Every
row carries evidence (a quote or line reference) and names WHERE the fix
belongs: source file, answer bank/template, memory store, or a new skill.

## Anti-Patterns

- **Editing any audited file.** Report-only — even 🟢 zero-risk deletions are
  recommendations, not actions. "Auto-fix" promises contradict the
  rendered-file guard and are out of contract.
- **Recommending a direct edit to a rendered file.** SOUL.md / USER.md /
  ACCESS_POLICY.md / HEARTBEAT.md edits are overwritten by the next
  `gbrain bootstrap render`. Target the answer bank or template, then
  re-render.
- **Raw model API calls for judging.** The eval runner owns provider config,
  receipts, and verdict aggregation — route through `gbrain eval cross-modal`.
- **Hardcoding model IDs.** Resolve the judge from the user's model tiers;
  model names in a skill body rot.
- **Running the full multi-model panel by default.** It is an explicit opt-in;
  the single-cheap-model pass is the default for cost reasons.
- **Auditing on-demand content as if always-loaded.** Skills and reference
  docs don't pay the per-turn tax; flagging them inflates savings numbers.
- **Inventing token counts.** Measure with the pre-pass; estimates are labeled
  as `~N` chars/4 approximations.
- **Rewriting identity content yourself.** If a finding is about WHAT an
  identity file says (wrong persona, outdated profile), route to soul-audit —
  the interview is the only author of that content.

## Dedup

- **soul-audit** — identity CONTENT via interview: what SOUL.md/USER.md
  should SAY, sourced from the user's own words. context-audit is
  token/structure hygiene: what the stack COSTS per turn, where it repeats or
  contradicts itself. A finding like "USER.md's profile is outdated" hands
  off to soul-audit; "USER.md restates 800 tokens already in SOUL.md" stays
  here. Both respect the same rendered-file rule.
- **skill-optimizer** — tunes ONE skill's body against a benchmark and can
  mutate it. context-audit never mutates and looks only at always-loaded
  files; skills appear only as extraction destinations.
- **functional-area-resolver** — the compression TECHNIQUE for oversized
  routing tables (>=12KB). context-audit may cite it as the recommended fix
  when a routing section is the finding; it never applies it.
- **skillpack-check** — install/runtime health (DB, worker, migrations), not
  context size or prompt content.
- **cross-modal-review** — general second-opinion gate on arbitrary work
  products. context-audit uses the same underlying runner but as its own
  fixed judging step with audit-specific pass criteria; asking for "a second
  opinion on this code" routes there, not here.

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [garrytan](https://skillsagentes.com/creators/garrytan.md) — 134 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Setup](https://skillsagentes.com/skills/garrytan/gbrain/setup.md): Configura GBrain con auto-aprovisionamiento de Supabase o PGLite, inyección en AGENTS.md y primera importación.
- [Maintain](https://skillsagentes.com/skills/garrytan/gbrain/maintain.md): Chequeos de salud del brain: aplicación de back-links, auditoría de citas, validación de filing, detección de info obsoleta, páginas huérfanas y benchmarks.
- [Schema Unify](https://skillsagentes.com/skills/garrytan/gbrain/schema-unify.md): Migra un brain de gbrain-base a la taxonomía de 14 tipos canónicos de gbrain-base-v2 usando gbrain onboard --check y el handler Minion unify-types.
- [Retrieval Reflex](https://skillsagentes.com/skills/garrytan/gbrain/retrieval-reflex.md): Cuándo y qué recuperar: abre la página del brain de una entidad relevante antes de responder desde memoria.
- [Minion Orchestrator](https://skillsagentes.com/skills/garrytan/gbrain/minion-orchestrator.md): Skill unificado de Minions para jobs deterministas de shell y orquestación de subagentes LLM: cola durable, observable y controlable, más la doctrina de ejecución durable para operaciones largas.

## Skills relacionadas

- [Gbrain Upgrade](https://skillsagentes.com/skills/garrytan/gbrain/gbrain-upgrade.md): Mantiene gbrain actualizado: cuando aparece un marcador UPGRADE_AVAILABLE, aplica la actualización según el modo configurado (notify o auto), siempre con gbrain self-upgrade.
- [Frontmatter Guard](https://skillsagentes.com/skills/garrytan/gbrain/frontmatter-guard.md): Valida y repara automáticamente el frontmatter YAML de las páginas del brain antes de que entren corruptas, envolviendo la CLI `gbrain frontmatter`.”
- [Reports](https://skillsagentes.com/skills/garrytan/gbrain/reports.md): Guarda y carga reportes con timestamp y routing por keyword; incluye el Actionability Gate que revisa enlaces rotos, muertos, indirectos o faltantes antes de entregar briefings o reportes.
- [Query](https://skillsagentes.com/skills/garrytan/gbrain/query.md): Responde preguntas usando el conocimiento del brain con búsqueda en 3 capas, síntesis y propagación de citas; úsalo cuando el usuario pregunte, busque o necesite información del brain.
- [Measure Before You Fix](https://skillsagentes.com/skills/garrytan/gbrain/measure-before-you-fix.md): Antes de arreglar una alerta de lentitud, stale o timeout, mide el paso tú mismo con un cronómetro en vez de un cambio de código: triage de operaciones basado en medición previa.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)