Mk Context Audit

---
name: "mk-context-audit"
description: "Read-only audit of the project's agent-tree structural overhead vs the context window. NOT for cost tracking (budget skill); NOT for read/compact decisions (mk:context-engineering)."
---

# the context-audit skill — Context Window Structural Audit

Read-only audit of the project's agent-tree (`.cursor/` + `.cursor/skills/`) structural overhead. Surfaces what is loaded into
every host-runtime session and how much of the context window it consumes,
then recommends the highest-leverage trims.

Complementary lens: `mewkit inventory --substrate` shows the same artifact set
grouped by the responsibility each serves (covered / partial / missing), so a trim
can be checked against responsibility coverage before removing an artifact. The
per-phase read budget that bounds what an audit-driven session should load lives in
`rules/context-budget-rules.md`.

## When to Use

Three concrete triggers:

1. **Pre-add capacity check** — before adding a new agent, skill, or rule file,
   confirm the project is below the 25% structural-overhead threshold.
2. **Post-degradation diagnostic** — when sessions feel slow, off-topic, or
   over-compacted, audit to see if structural overhead has grown past 10%.
3. **Periodic health audit** — quarterly or on model upgrades, confirm
   the always-on bundle still pays its keep (paired with the dead-weight audit
   in `harness-rules.md` Rule 7).

## Context vs Cost (Boundary)

| Concern                         | Mechanism                                                | Unit          |
| ------------------------------- | -------------------------------------------------------- | ------------- |
| Monetary cost                   | `the budget skill` + `../autobuild/scripts/budget-tracker.sh`  | USD           |
| Window utilization (this skill) | `the context-audit skill` + `scripts/inventory-context.sh`      | tokens / %    |

The three concerns are deliberately separate. This skill measures only what
is **statically loaded** into every session — the always-on bundle. Conversation
history, tool output, and active edits live elsewhere.

## Workflow

The slash command runs the pipeline:

```bash
SCAN_ROOT="${1:-$PWD}"
bash .cursor/skills/context-audit/scripts/inventory-context.sh "$SCAN_ROOT" \
  | bash .cursor/skills/context-audit/scripts/estimate-tokens.sh \
  | bash .cursor/skills/context-audit/scripts/format-audit-report.sh
```

Output is markdown, printed to terminal. The skill does NOT write any files.

Steps:

1. **Inventory** — `inventory-context.sh` walks the agent tree and emits raw
   byte/line counts per category (AGENTS.md chain, agents, skills, rules,
   MCP) as JSON.
2. **Estimate** — `estimate-tokens.sh` enriches the inventory with
   `estimated_tokens` (chars/4 heuristic, mirrors `budget-tracker.cjs`) and
   computes `totals` including `structural_overhead_pct` against a 200K window.
3. **Format** — `format-audit-report.sh` emits a 5-section markdown report:
   header, summary table, top consumers, recommendations, footer.
4. **Banner** — the formatter selects a banner based on
   `structural_overhead_pct`:
   - `< 10%`  → Healthy
   - `10–25%` → Watch
   - `≥ 25%`  → Action recommended

## Output Format

```
# Context Audit — <scan_root>
*Scanned at <timestamp> · model window 200K tokens · banner: <Healthy|Watch|Action>*

## Summary
| Category | Components | Bytes | Tokens | % of Window |
| ...      | ...        | ...   | ...    | ...          |

## Top Consumers
1. <component> ~<tokens> (<path>)
... (top 10)

## Recommendations
1. <priority finding> — saves ~<tokens>
... (sorted by token impact, descending)

## How to Act
- Cost: see `the budget skill`
- Runtime trim: see `mk:lazy-agent-loader`
```

The 10% / 25% thresholds are the canonical source of truth for token-overhead
banners — see `references/token-cost-model.md`. They are NOT linked to
`MEOWKIT_BUDGET_*` env vars (those are USD amounts, not token percentages).

## Integration Points

- **Reuses, does not duplicate:** `packages/mewkit/src/token-estimator/index.ts`
  is the canonical chars/4 source. Shell scripts inline the same heuristic with
  a citation comment, avoiding a Node bridge that would require `dist/`.
- **Reads, does not write:** `.meowkit/telemetry/cost-log.json`,
  the project's agent-tree, `.mcp.json`. No file writes anywhere.
- **No env vars introduced.** Window size is hard-coded 200K; override deferred
  until a real 1M-context use case appears.
- **Discovery:** via `keywords:` frontmatter and a cross-reference from
  `the budget skill`. There is no separate routing rule.

## Gotchas

(none yet — grow from observed failures)

## Related Rules

- Skill authoring conventions — discovery + Gotchas section requirements
- `AGENTS.md` (Data & injection boundary) Rule 11 — Skill Rule of Two; this skill
  scores 2 of 3 (untrusted SCAN_ROOT input + filename inventory may surface
  sensitive paths) so paths are canonicalized via `realpath` and never executed.