context-audit

name	context-audit
description	Token-hygiene pass for the Ralph loop. This skill should be used before reading another large file or near the end of a Continue-As-New window: it drops stale file reads, prefers targeted Grep over full-file Read, and consolidates repeated file-scan patterns to stop the drift where each iteration re-reads the same file and burns prompt cache. Works with the SDK ContextManager (sdk/ralph_sdk/context.py) and the Continue-As-New trigger.
version	1.1.0
ralph	true
ralph_version_min	2.17.0
attribution	Authored for Ralph runtime, drawing on prompt-cache best practices for Claude
user-invocable	true
disable-model-invocation	false
allowed-tools	["Read","Grep","Glob","Bash"]

context-audit — Treat Context Like a Budget

Ralph's long sessions (Continue-As-New kicks in at 20 iterations / 120 minutes) accumulate context debt: every full-file Read, every stale directory listing, every echoed JSON payload stays in the working window until it's flushed. This skill trims that debt before it becomes a problem, not after the circuit breaker trips.

When to invoke

Trigger this skill when any of these hold:

• Current loop count within this session is ≥ 10 and the task is non-trivial — you're in the second half of a Continue-As-New window and token cost is compounding.
• The next task requires reading a large file (> 500 lines) and that file (or a sibling) was already Read in this session.
• The previous loop's prompt-cache hit rate (visible in .ralph/metrics/*.jsonl) dropped below 50% — context is churning.
• You're about to invoke a sub-agent and you want to pass a compact handoff, not a firehose.

Skip this skill for the first 3 loops of a session — early loops need room to explore, and audit overhead isn't paid back yet.

Ralph-specific guidance

Four disciplines, in order of payoff:

1. Prefer Grep over Read for targeted questions

If the question is "does this function exist in ralph_loop.sh?", the answer is one Grep invocation. Reading the whole ~2,300-line file wastes ~60k tokens to answer a one-bit question. Use Read with offset/limit when you need the exact surrounding lines.

2. Drop stale reads between related iterations

A file Read 8 loops ago is probably no longer the live version of that file — it may have been edited by Claude, by a sub-agent in a worktree, or by the PostToolUse hooks. When in doubt, Re-Read a slice, not the whole file. The ContextManager in the SDK ( sdk/ralph_sdk/context.py::ContextManager) already trims fix_plan.md progressively; lean on that signal — if it pruned a section, don't ask for the whole thing again.

3. Consolidate repeated scan patterns

If you've run the same Grep across lib/, sdk/, and tests/ three times in a session, the search space isn't changing. Cache the result in a local variable (for the current iteration) and pass it to the sub-agent instead of telling the sub-agent to re-grep.

4. Respect cache-prefix stability

Claude's prompt cache keys off a stable prefix. In Ralph terms: templates/PROMPT.md + the .ralphrc + CLAUDE.md form the stable prefix. Do not restructure them mid-session; append-only changes (new task under an existing section) preserve the cache. The PromptParts/PromptCacheStats classes (Phase 17) track this.

Integration with sub-agents

• ralph-explorer (Haiku) — delegate wide-scope search here. Explorer runs in its own context window, so its results come back as a short summary instead of 200 matching lines in the main window. Net cache gain is significant.
• ralph-tester / ralph-reviewer / ralph-architect — when you hand off, hand off a summary plus specific file paths, not the full conversation so far. A one-paragraph brief + 3 file paths outperforms dumping the session transcript every time.
• Continue-As-New — at the session boundary (iteration 20 or 120 min), the loop auto-resets but carries forward essential state (current task, progress, recommendation) via ContinueAsNewState. Before the reset fires, run this skill once so the next session starts from a compact baseline.

Exit criteria

You're done with this skill when all of:

1. The next planned action uses the minimum viable read (Grep, or Read with offset/limit, instead of full-file Read).
2. You've identified and skipped at least one file that was already freshly read earlier in the same iteration.
3. If a sub-agent is next, the handoff brief is ≤ 200 words.

Anti-patterns

• "Let me read the whole file to get context" — full Reads are a last resort, not a first move. Grep first.
• Re-Reading after every Edit — the Edit tool's response already echoes the post-edit state of the affected lines; don't Read the whole file to confirm.
• Passing the entire conversation to a sub-agent — sub-agent prompts should be self-contained briefs, not transcripts. The Agent tool prompt is for the sub-agent, not a mirror of the main session.
• Reading ralph.log — that log grows unbounded mid-session; the structured fields you need are in status.json or .exit_signals.