| name | strategic-compact |
| description | Hook-based compaction suggestions at logical task boundaries |
| version | 0.1.0 |
| level | 2 |
| triggers | ["compact now","context getting full","running out of space","should i compact"] |
| context_files | ["context/learnings.md"] |
| steps | [{"name":"Tool Invocation Count","description":"Track tool calls since last compact or session start"},{"name":"Boundary Detection","description":"Identify if current state is at a logical task boundary"},{"name":"Compact Decision","description":"Apply decision guide to recommend compact or defer"},{"name":"State Preservation","description":"Remind user to capture critical state before compacting"},{"name":"Context Documentation","description":"Update learnings.md with pre-compact state if needed"}] |
Strategic Compact Skill
Suggests /compact at logical task boundaries. Prevents premature compaction that loses critical context.
What Claude Gets Wrong Without This Skill
Without strategic compaction guidance, Claude either:
- Compacts too early and loses debugging context mid-investigation
- Compacts too late and runs out of context window during critical work
- Doesn't preserve state before compacting, losing progress tracking
- Compacts at random moments instead of natural breakpoints
Strategic compaction maintains context hygiene without disrupting workflow.
Tool Invocation Tracking
Compaction suggestions triggered by tool call count:
- 50 tool calls: First suggestion (soft reminder)
- 75 tool calls: Second reminder (moderate urgency)
- 100+ tool calls: Strong recommendation (context pressure likely)
Count these tools:
- Read, Write, Edit (file operations)
- Bash (command execution)
- Grep, Glob (search operations)
- Task (subagent spawning)
Don't count: TodoWrite, AskUserQuestion (metadata operations)
Integration with existing preserve-on-compact.sh hook: hook fires on /compact; this skill decides when to suggest it.
Decision Guide
| Transition | Compact? | Reasoning |
|---|
| Research → Planning | YES | Research artifacts captured, planning starts fresh |
| Planning → Implementation | YES | Plan finalized, implementation is new phase |
| Mid-Implementation | NO | Variable state, error traces, partial progress would be lost |
| After Failed Approach | YES | Dead end documented in learnings.md, fresh start needed |
| Feature Complete → Testing | YES | Implementation done, testing is verification phase |
| Bug Hunt in Progress | NO | Debugging requires full context (stack traces, state, prior attempts) |
| After Successful PR Merge | YES | Work complete, next task starts clean |
General Rule: Compact at phase transitions where the prior phase's working context is no longer needed for the next phase.
What Survives Compaction
Claude Code's compaction preserves:
- CLAUDE.md and all .claude/ configuration
- Recent tool use (last ~10-15 operations)
- Current file state (all files as they exist now)
- Conversation summary (condensed key decisions)
Lost during compaction:
- Detailed reasoning for past decisions
- Full error messages and stack traces
- Alternative approaches that were tried and rejected
- Intermediate variable states and debugging context
- Specific code snippets from earlier discussion
What to Preserve Before Compacting
Before compacting, ensure these are captured:
In context/learnings.md:
- Patterns discovered this session
- Mistakes made and their causes
- Dead ends: approaches tried that didn't work (and why)
- Key decisions and their rationale
In context/decisions.md:
- Architectural decisions (if any ADRs were made)
- Tradeoffs accepted
In code comments:
- Complex logic explanations (if implementation is subtle)
- Constraint documentation (if unusual requirements)
In test files:
- Regression tests for bugs found this session
The preserve-on-compact.sh hook prompts for this, but this skill provides the content checklist.
Integration with Hooks
preserve-on-compact.sh (PreCompact hook):
- Fires when user runs /compact
- Prompts: "Capture state in learnings.md?"
- This skill defines what "state" means
Recommended enhancement:
Add tool invocation counter to preserve-on-compact.sh:
TOOL_COUNT=$(grep -c "Tool:" .claude/session.log 2>/dev/null || echo 0)
if [ "$TOOL_COUNT" -gt 50 ]; then
echo "50+ tool calls since last compact. Consider capturing state."
fi
(Note: session.log doesn't exist in current Claude Code. This is aspirational for future hook enhancements.)
Anti-Patterns
Compacting mid-debugging: You're investigating a bug, have a stack trace, tried 3 approaches. Compacting now loses all that context. Finish the investigation first.
Compacting to "clean up": Compaction isn't for aesthetics. Only compact at task boundaries or when context pressure is real (100+ tool calls).
Ignoring the 50-call reminder: If you're at 50 calls and still in the same task, that's a signal the task might be too large. Consider checkpointing or breaking it down.
Compacting without preserving dead ends: "I tried X but it failed because Y" is critical for the next session. Write it to learnings.md before compacting.
Mandatory Checklist
- Verify tool invocation count is tracked or estimated (50/75/100+ thresholds)
- Verify current task state identified (mid-implementation, post-planning, debugging, etc.)
- Verify decision guide consulted (transition type determines compact recommendation)
- Verify if compacting: critical state captured in learnings.md (dead ends, patterns, decisions)
- Verify if compacting: no active debugging in progress (stack traces and error context would be lost)
- Verify if deferring: user informed why compaction deferred and when to revisit
- Verify preserve-on-compact.sh hook will fire if user proceeds with /compact