lidge-jun/strategic-compact

Strategic Compact

Suggests manual compaction at strategic points rather than relying on arbitrary auto-compaction.

When to Use

• Running long sessions approaching context limits (200K+ tokens)
• Working on multi-phase tasks (research → plan → implement → test)
• Switching between unrelated tasks within the same session
• After completing a major milestone
• When responses slow down or become less coherent (context pressure)

Why Strategic Compaction?

Auto-compaction triggers at arbitrary points — often mid-task, losing important context with no awareness of logical boundaries.

Strategic compaction at logical boundaries:

• After exploration, before execution — compact research context, keep implementation plan
• After completing a milestone — fresh start for next phase
• Before major context shifts — clear exploration context before a different task

Hook Setup

The suggest-compact.js script runs on PreToolUse (Edit/Write) and tracks tool calls, suggesting compaction at a configurable threshold (default: 50 calls), with reminders every 25 calls after.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "node scripts/suggest-compact.js" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "node scripts/suggest-compact.js" }]
      }
    ]
  }
}

Environment variable: COMPACT_THRESHOLD — tool calls before first suggestion (default: 50).

Compaction Decision Guide

| Phase Transition | Compact? | Why | |-----------------|----------|-----| | Research → Planning | Yes | Research context is bulky; plan is the distilled output | | Planning → Implementation | Yes | Plan is saved to a file; free up context for code | | Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus | | Debugging → Next feature | Yes | Debug traces pollute context for unrelated work | | Mid-implementation | No | Losing variable names, file paths, and partial state is costly | | After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |

What Survives Compaction

| Persists | Lost | |----------|------| | Project config / instructions | Intermediate reasoning and analysis | | Task lists (saved to file) | File contents previously read | | Memory files | Multi-step conversation context | | Git state (commits, branches) | Tool call history and counts | | Files on disk | Nuanced preferences stated verbally |

Best Practices

1. Compact after planning — once the plan is saved to a file, compact to start fresh
2. Compact after debugging — clear error-resolution context before continuing
3. Preserve mid-implementation context — keep context for related changes
4. Write before compacting — save important context to files or memory first
5. Add a summary when compacting — e.g., "Focus on implementing auth middleware next"

Token Optimization Patterns

Trigger-Table Lazy Loading

Instead of loading full skill content at session start, use a trigger table mapping keywords to skill paths. Skills load only when triggered, reducing baseline context by 50%+.

Context Composition Awareness

Monitor what consumes the context window:

• Project config — always loaded, keep lean
• Loaded skills — each adds 1–5K tokens
• Conversation history — grows with each exchange
• Tool results — file reads, search results add bulk

Duplicate Instruction Detection

Common sources of duplicate context:

• Same rules in global and project-level configs
• Skills that repeat project config instructions
• Multiple skills covering overlapping domains