Strategic compact

Strategic Compact Skill

Suggests manual /compact at strategic points in your workflow rather than relying on arbitrary auto-compaction.

When to Activate

• Running long sessions that approach 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 and starting new work
• 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
• No awareness of logical task boundaries
• Can interrupt complex multi-step operations

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 different task

How It Works

The suggest-compact.sh script runs on PreToolUse (Write|Edit) and:

1. Tracks tool calls — Counts tool invocations in session
2. Threshold detection — Suggests at configurable threshold (default: 50 calls)
3. Periodic reminders — Reminds every 25 calls after threshold

Hook Setup

The harness wires this for you — installing this skill also writes the hook into the project's .claude/settings.json. Do not paste the block below on top of that; two registrations mean the counter advances twice per tool call and the suggestion fires at half the threshold.

What the installer writes, for reference (project scope, alongside protect-files.sh on the same matcher):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/skills/strategic-compact/suggest-compact.sh\"",
            "async": true,
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Copy it only if you are wiring the skill by hand outside the installer — and check the file for an existing entry first.

Configuration

Environment variables:

• COMPACT_THRESHOLD — Tool calls before first suggestion (default: 50)

Compaction Decision Guide

Use this table to decide when to compact:

Phase Transition	Compact?	Why
Research → Planning	Yes	Research context is bulky; plan is the distilled output
Planning → Implementation	Yes	Plan is in TodoWrite or 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

Understanding what persists helps you compact with confidence:

Persists	Lost
CLAUDE.md instructions	Intermediate reasoning and analysis
TodoWrite task list	File contents you previously read
Memory files (~/.claude/memory/)	Multi-step conversation context
Git state (commits, branches)	Tool call history and counts
Files on disk	Nuanced user preferences stated verbally

Best Practices

1. Compact after planning — Once plan is finalized in TodoWrite, compact to start fresh
2. Compact after debugging — Clear error-resolution context before continuing
3. Don't compact mid-implementation — Preserve context for related changes
4. Read the suggestion — The hook tells you when, you decide if
5. Write before compacting — Save important context to files or memory before compacting
6. Use /compact with a summary — Add a custom message: /compact 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 that maps keywords to skill paths. Skills then cost their descriptor while resident and their body only when triggered. How much that saves depends entirely on which skills you have installed — measure yours with npm run cost:report rather than assuming a ratio:

Trigger	Skill	Load When
"test", "tdd", "coverage"	tdd-workflow	User mentions testing
"security", "auth", "xss"	security-review	Security-related work
"deploy", "ci/cd"	deployment-patterns	Deployment context

Context Composition Awareness

Monitor what's consuming your context window:

• CLAUDE.md files — Always loaded, keep lean
• Loaded skills — Each skill 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 both ~/.claude/rules/ and project .claude/rules/
• Skills that repeat CLAUDE.md instructions
• Multiple skills covering overlapping domains

Context Optimization Tools

• token-optimizer MCP — content deduplication
• context-mode — context virtualization

Both are third-party tools this harness does not ship, measure, or vouch for. Their vendors publish dramatic reduction figures; treat those as marketing until you have measured your own workload.

Related

• The Longform Guide — Token optimization section
• Memory persistence hooks — For state that survives compaction
• continuous-learning-v2 skill — observes sessions into instincts (v1 was deprecated upstream)