# Strategic Compact

> Hook-based compaction suggestions at logical task boundaries

- Skill: `andrem-sec/strategic-compact` (Agent Skill)
- Install (CLI): `npx skillmds@latest add andrem-sec/strategic-compact`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andrem-sec/strategic-compact/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: andrem-sec (https://skillmd.com/u/andrem-sec)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/andrem-sec/strategic-compact

---


# 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:
1. Compacts too early and loses debugging context mid-investigation
2. Compacts too late and runs out of context window during critical work
3. Doesn't preserve state before compacting, losing progress tracking
4. 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:
```bash
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

1. Verify tool invocation count is tracked or estimated (50/75/100+ thresholds)
2. Verify current task state identified (mid-implementation, post-planning, debugging, etc.)
3. Verify decision guide consulted (transition type determines compact recommendation)
4. Verify if compacting: critical state captured in learnings.md (dead ends, patterns, decisions)
5. Verify if compacting: no active debugging in progress (stack traces and error context would be lost)
6. Verify if deferring: user informed why compaction deferred and when to revisit
7. Verify preserve-on-compact.sh hook will fire if user proceeds with /compact