// Strategies for compressing context to maximize token efficiency
Analyzes existing codebases to understand structure, patterns, and technical debt
Search-first skill to reduce unnecessary file reads by searching before loading
Monitors context complexity and triggers state dumps before quality degrades
Systematic debugging with persistent state and fresh context advantages
Requires proof before marking work complete — no "trust me, it works"
Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and state management
| name | context-compressor |
| description | Strategies for compressing context to maximize token efficiency |
Core principle: Compress aggressively, decompress only when needed.
When: You've fully understood a file and may need to reference it later.
How:
## File Summary: src/auth/login.ts
**Purpose:** Handles user login via email/password
**Key functions:**
- handleLogin(req, res) → Validates credentials, returns JWT
- validateCredentials(email, password) → Checks against DB
**Dependencies:** bcrypt, jose, database
**Tokens saved:** ~400 (95 lines not reloaded)
Use instead of: Re-reading the full file
When: You need to understand a file's structure but not implementation details.
How:
## Outline: src/services/payment.ts (127 lines)
- L1-15: Imports and types
- L17-35: PaymentService class
- L20: constructor(config)
- L25: processPayment(amount, method)
- L45: refund(transactionId)
- L67: getHistory(userId)
- L90-127: Helper functions
Tokens: ~50 vs ~500 for full file
When: You've already seen a file and need to understand changes.
How:
## Changes to: src/config.ts
Added:
- L45: TOKEN_BUDGET_THRESHOLD = 0.5
- L46: COMPRESSION_ENABLED = true
Modified:
- L12: MAX_CONTEXT → increased from 100000 to 150000
Use for: Reviewing modifications, understanding updates
When: You need to track a file without loading it.
How:
## References
| File | Last Seen | Summary | Load If |
|------|-----------|---------|---------|
| auth.ts | Task 2 | Login handling | Auth bugs |
| db.ts | Task 1 | Postgres client | DB errors |
| utils.ts | Never | Utility funcs | Helper needed |
Cost: ~10 tokens vs ~200+ per file
When: Unsure how much detail is needed.
Process:
L1: Outline → "I see handleLogin at L25"
L2: Function → "handleLogin validates then calls createToken"
L3: Related → "createToken uses jose.sign with HS256"
L4: Full → Only for complex debugging
| Trigger | Action |
|---|---|
| After understanding a file | Create summary |
| Switching tasks | Compress previous context |
| Budget at 50% | Aggressive outline mode |
| Budget at 70% | Summary-only mode |
| End of wave | Full compression pass |
When you need details from compressed context:
## Decompression Log
| File | Reason | Level | Tokens |
|------|--------|-------|--------|
| auth.ts | Debug login | L2 (func) | +150 |
| db.ts | Check query | L3 (snippet) | +50 |
## 📦 [filename]
**Purpose:** [one line]
**Key exports:** [list]
**Dependencies:** [list]
**Patterns:** [notable patterns used]
**Watch for:** [gotchas or edge cases]
## 📋 [filename] (N lines)
- L[start]-[end]: [section name]
- L[n]: [key item]
- L[n]: [key item]
## Δ [filename]
**+** [additions]
**-** [removals]
**~** [modifications]
Works with:
token-budget — Triggers compression at thresholdscontext-fetch — Provides input for compressioncontext-health-monitor — Monitors compression effectiveness❌ Keeping full files in mental context — Compress after understanding ❌ Re-reading instead of referencing — Use summaries ❌ Loading full file for one function — Use outline + target ❌ Skipping compression "to save time" — Costs more later
Part of GSD v1.6 Token Optimization. See docs/token-optimization-guide.md for examples.