Context Audit Skill

Use this skill when experiencing slow sessions, context budget issues, or token limit warnings.

When to Use

• •Context budget exceeded warnings
• •Session feels slow or unresponsive
• •Loading too many files unnecessarily
• •Need to optimize context for better performance

Do NOT use when:

• •First starting a session (use start-session skill instead)
• •Working on focused task with minimal context

Inputs

Required

• •Current context size: Estimated tokens loaded
• •Session symptoms: What feels slow or wrong

Optional

• •Target budget: Desired token limit (default: 10k)
• •Files accessed: List of files loaded during session

Steps

Step 1: Measure Current Context

What to do: Count tokens and files currently loaded.

Methods:

1. •

   Check session metrics:

   • •Look for token usage indicators in your AI tool
   • •Note any "context budget exceeded" warnings
2. •

   Estimate from files:

   bash

   # Count lines in recently accessed files
   find src/ tests/ -name "*.py" -type f -mtime -1 -exec wc -l {} + | tail -1
   
   # Rough token estimate (lines * 5 for Python)
   

3. •

   List loaded files: Review session log to see which files were read

Validation:

• • Have rough token count
• • Know how many files were loaded
• • Identified any large files (>200 lines or 10KB)

Step 2: Identify Context Drift

What to do: Find unnecessary context that has accumulated.

Common sources of drift:

1. •

   Old session logs:

   • •Check if logs > 5 entries were loaded
   • •Archive or summarize old logs
2. •

   Full file reads:

   • •Did you read entire files when only a section was needed?
   • •Check for read operations on large files
3. •

   Multiple versions:

   • •Are you tracking multiple branches/versions?
   • •Focus on current working state only
4. •

   Documentation overload:

   • •Loaded full docs when quick reference would suffice?
   • •Use .codex/QUICKSTART.md instead of full guides

Validation:

• • Identified >3 sources of drift
• • Noted files that were read unnecessarily
• • Found outdated information in context

Step 3: Apply Context Optimization

What to do: Implement strategies to reduce context size.

Strategy A: File Selection

# Use grep instead of reading full files
grep -n "def process_data" src/*.py

# Read only specific sections
read src/main.py offset=100 limit=20

# Skip auto-generated files
# Don't read: __pycache__, node_modules, .venv

Strategy B: Summarize Before Loading Instead of reading 5 old session logs:

# Create a summary document
## Context Summary (YYYY-MM-DD)
- Completed: [List major achievements]
- Current blockers: [Any blockers]
- Next priority: [What to work on]
- Key files: [Important paths]

Strategy C: Tiered Loading Follow the tiered approach from AGENTS.md:

1. •Tier 1 (Always): AGENTS.md, README.md, .agent/CONTEXT.md
2. •Tier 2 (As needed): Schedule, standards, specific code
3. •Tier 3 (On-demand): Full architecture, history

Strategy D: Use Search

# Find relevant code without loading everything
grep -r "class DataModel" src/
find . -name "*.py" -exec grep -l "import pandas" {} \;

Validation:

• • Reduced files loaded by 50%+
• • Using targeted reads instead of full files
• • Summarized old context into brief notes

Step 4: Validate Performance

What to do: Test that optimizations improved performance.

Metrics to check:

1. •Response time: Are AI responses faster?
2. •Token usage: Staying within budget?
3. •Accuracy: Does AI still have necessary context?

Test questions:

• •"What are the current project priorities?" (should reference CONTEXT.md)
• •"What's the next task to work on?" (should reference schedule)
• •"Where is the config module?" (should know src/ structure)

Validation:

• • Responses are faster (< 5 seconds for simple queries)
• • No budget warnings
• • AI has correct context for current work

Step 5: Document Changes

What to do: Record optimization decisions in session log.

What to document:

## Context Optimization
**Before:**
- Loaded files: [List]
- Estimated tokens: [Number]
- Issues: [What was slow]

**Optimizations Applied:**
1. [Strategy used and result]
2. [Strategy used and result]

**After:**
- Loaded files: [List]
- Estimated tokens: [Number]
- Performance: [Improvement noted]

**Maintaining:**
- [Rule for future sessions]

Validation:

• • Session log updated with optimization details
• • Future sessions can learn from this audit

Context Budget Guidelines

Per-Role Budgets

• •Navigator: ≤2.5k tokens
• •Specialist: ≤2k tokens
• •Per-session total: Prefer ≤10k tokens, max 50k

Warning Signs

• •Response time > 10 seconds
• •"Context limit approaching" warnings
• •AI asks for clarification on basic project info
• •Repeated "loading file..." messages

Optimization Targets

• •Files loaded per session: 5-10 max
• •Session logs read: 3-5 max
• •Documentation: 1-2 pages at a time
• •Code files: Only sections being modified

Validation

Success Criteria

• • Context size reduced by 30% or more
• • Response times improved
• • No budget exceeded warnings
• • Session log documents optimizations
• • Clear rules for future context management

Verification Commands

# Check for large files
find . -name "*.md" -size +10k -type f
find . -name "*.py" -size +50k -type f

# Count recent session logs
ls -1 session_logs/*/ | wc -l

# Estimate context in docs directory
du -sh docs/

Common Mistakes

1. •Over-optimizing: Removing too much context causes confusion
2. •Not documenting: Future sessions repeat the same mistakes
3. •One-time fix: Context management needs ongoing attention
4. •Ignoring warnings: Address budget issues early, not after failure

Links

• •Context: .agent/CONTEXT.md
• •Agent Guidance: .agent/AGENTS.md
• •Start Session: .agent/skills/start-session/SKILL.md
• •Troubleshooting: docs/troubleshooting.md