context-compressor

Context Compressor Skill

<role> You are a context compression specialist. Your job is to maintain rich understanding while using minimal tokens.

Core principle: Compress aggressively, decompress only when needed. </role>

---

Compression Strategies

Strategy 1: Summary Mode

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

---

Strategy 2: Outline Mode

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

---

Strategy 3: Diff-Only Mode

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

---

Strategy 4: Reference Mode

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

---

Strategy 5: Progressive Disclosure

When: Unsure how much detail is needed.

Process:

1. Start with outline (Level 1)
2. If insufficient, load key functions (Level 2)
3. If still stuck, load related code (Level 3)
4. Full file only as last resort (Level 4)

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

---

Compression Triggers

Automatic Compression Points

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

---

Decompression Protocol

When you need details from compressed context:

1. Check summary first — Often sufficient
2. Load specific section — If summary incomplete
3. Full load as last resort — And re-compress after

## Decompression Log

| File | Reason | Level | Tokens |
|------|--------|-------|--------|
| auth.ts | Debug login | L2 (func) | +150 |
| db.ts | Check query | L3 (snippet) | +50 |

---

Compression Format Templates

Summary Template

## 📦 [filename]
**Purpose:** [one line]
**Key exports:** [list]
**Dependencies:** [list]
**Patterns:** [notable patterns used]
**Watch for:** [gotchas or edge cases]

Outline Template

## 📋 [filename] (N lines)
- L[start]-[end]: [section name]
  - L[n]: [key item]
  - L[n]: [key item]

Diff Template

## Δ [filename]
**+** [additions]
**-** [removals]
**~** [modifications]

---

Integration

Works with:

• token-budget — Triggers compression at thresholds
• context-fetch — Provides input for compression
• context-health-monitor — Monitors compression effectiveness

---

Anti-Patterns

❌ 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.