strategic-compact

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• should I compact now
• my session is getting slow
• set up a compaction reminder hook

What it does

strategic-compact is the compaction-discipline skill in Affaan M’s everything-claude-code — see skills/strategic-compact. It pushes manual /compact at logical task boundaries rather than waiting for auto-compaction to fire at an arbitrary token threshold. Auto-compaction has no awareness of phase boundaries — it can trigger mid-implementation, losing variable names, file paths, and partial state at the worst possible moment.

The skill ships a small PreToolUse hook (suggest-compact.js) that counts tool invocations and prompts the operator at a configurable threshold (COMPACT_THRESHOLD, default 50 calls) with periodic reminders every 25 calls after. The decision guide pairs phase transitions to compact / don’t-compact verdicts: research → planning is a yes, planning → implementation is a yes, mid-implementation is a no (losing context is costly here), after-a-failed-approach is a yes (clear the dead-end reasoning before trying again).

The “what survives compaction” table is the operational core: CLAUDE.md instructions, the TodoWrite list, memory files, git state, and on-disk files all persist; intermediate reasoning, previously-read file contents, multi-step conversation context, and tool-call history are lost. The advice is to write important context to a file or memory before compacting, and to use /compact with a custom message (/compact Focus on implementing auth middleware next) so the next turn has a deliberate anchor.

When to use it

• Long sessions approaching 200K+ tokens where auto-compaction is about to fire
• Multi-phase tasks (research → plan → implement → test) where the natural boundary between phases is a clean compaction point
• Switching from one unrelated task to another inside the same session
• After a failed approach, before trying a new direction — clear the dead-end reasoning
• After a major milestone and starting fresh work

When not to reach for it:

• Mid-implementation when you still need the file paths, variable names, and partial state from earlier turns
• Short sessions well below the context limit — compaction overhead exceeds the benefit
• Cost / spend tracking — that’s cost-tracking
• Auditing what’s loaded into context — that’s context-budget

Install

From affaan-m/everything-claude-code at skills/strategic-compact/. Drop the folder into ~/.claude/skills/strategic-compact/. The hook itself (suggest-compact.js) needs to live at ~/.claude/scripts/hooks/suggest-compact.js, and the PreToolUse entries (matchers Edit and Write per the upstream) go into ~/.claude/settings.json. Configurable via COMPACT_THRESHOLD env var.

What a session looks like

1. Threshold trip. Tool-call count crosses 50 (or whatever COMPACT_THRESHOLD is set to). The PreToolUse hook prints a suggestion: “Consider /compact — you’re at 52 calls.”
2. Operator checks the phase boundary. Research is done, the plan is in TodoWrite. This is a “yes” row in the decision guide.
3. Save anything fragile. Important reasoning that hasn’t been committed yet gets written to a memory file or a scratchpad markdown.
4. /compact with a custom message. “Focus on implementing the auth middleware per the plan in TodoWrite next.” The custom message becomes the new anchor.
5. Fresh start with what survived. CLAUDE.md, TodoWrite, memory, git state, on-disk files all intact. The conversation log is gone but the operational context isn’t.
6. Resume work. Next turn picks up where the plan left off without paying for the now-irrelevant research context.

The discipline that makes it work: compact at boundaries, not when the threshold trips alone. The hook is a reminder, not a command. The operator is the one who decides whether the current moment is a phase boundary or a mid-flight position where compaction would cost more than it saves.

Receipts

TODO — to be filled in from a real session. Once the hook has been wired in and /compact used at a real phase boundary, this section will capture: the actual tool-call threshold that produced the most useful suggestion (default 50 vs. whatever the operator settled on), which “survives compaction” item turned out to be wrong for the workflow (most likely partial work that should’ve been written to memory first), and whether using /compact with a custom message actually helped the next turn anchor on the right next step.

Source and attribution

From Affaan M’s everything-claude-code — an MIT-licensed skill collection covering harness construction, agent ops, video, payments, and platform-specific patterns.

License: MIT.

Quoting the boundary rule verbatim: “Strategic compaction at logical boundaries: after exploration, before execution — compact research context, keep implementation plan.” That’s the wedge — the operator picks the seam, the hook just reminds them when to look for one.