Context Compressor Skill

Core principle: Compress aggressively, decompress only when needed.

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:

Start with outline (Level 1)
If insufficient, load key functions (Level 2)
If still stuck, load related code (Level 3)
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:

Check summary first — Often sufficient
Load specific section — If summary incomplete
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.