strategic-compact

Why Strategic Compaction > Auto-Compaction

Auto-compaction operates on simple thresholds (token count, time elapsed) without understanding the semantic state of your work. This leads to several problems:

1. Mid-Task Disruption: Auto-compact might trigger while you're debugging a complex issue, losing the mental model you've built up over many interactions.

1. Context Fragmentation: Arbitrary cutoffs create artificial boundaries in your work history, making it harder to understand the full picture when resuming.

1. Lost Continuity: Important context about "why" decisions were made gets compacted away at random points rather than preserved at meaningful boundaries.

1. Incomplete State: Compacting mid-implementation can lose track of partially completed work, leading to duplicated effort or missed steps.

Strategic compaction instead:

• Monitors for logical boundaries in your work (task completion, phase transitions)
• Considers the semantic state of the session (actively debugging vs. between tasks)
• Provides suggestions rather than forcing compaction
• Integrates with context-saver to preserve critical state before compaction
• Respects your workflow rhythm rather than imposing arbitrary limits

The goal is compaction that feels like a natural pause point, not an interruption.

---

This skill operates primarily through the PreToolUse hook, passively monitoring session state and providing suggestions at appropriate moments.

Automatic Monitoring (PreToolUse Hook)

The skill attaches to every tool call, maintaining counters and evaluating whether the current moment represents a good compaction opportunity.

Manual Invocation

You can also invoke the skill directly:

• /strategic-compact - Check current session state and get recommendation
• /strategic-compact status - View tool counts and threshold proximity
• /strategic-compact now - Force a compaction suggestion (with context-saver integration)

---

How to Count Tool Calls

The skill maintains session state by tracking tool invocations. This is implemented through the PreToolUse hook which fires before each tool execution.

```yaml

# Session State Structure

session_state:

tool_counts:

total: 0 # All tool calls

significant: 0 # Tools that modify state or are complex

read_operations: 0 # Read, Glob, Grep operations

write_operations: 0 # Write, Edit, Bash operations

navigation: 0 # Directory changes, file searches

boundaries:

tasks_completed: 0 # TaskUpdate with status=completed

phases_completed: 0 # Major implementation phases

commits_made: 0 # Successful git commits

flags:

active_debugging: false # Currently in debug cycle

active_implementation: false # Mid-feature implementation

last_error_count: 0 # Errors in recent tool calls

timestamps:

session_start: null

last_boundary: null # Last logical boundary crossed

last_suggestion: null # Avoid repeated suggestions

```

Which Tools to Count

Significant Tools (count toward threshold):

• Edit - File modifications
• Write - File creation/overwrite
• Bash - Command execution (especially git, npm, build commands)
• NotebookEdit - Jupyter modifications
• TaskUpdate - Task state changes

Tracked but Weighted Lower:

• Read - File reading (0.5 weight)
• Glob - File pattern matching (0.3 weight)
• Grep - Content searching (0.3 weight)
• WebFetch / WebSearch - External lookups (0.5 weight)

Boundary Markers (reset considerations):

• TaskUpdate with status: completed - Task boundary
• Bash with git commit - Commit boundary
• Skill invocations for phase completion

Session State Tracking

State is maintained in-memory during the session. The PreToolUse hook updates counters before each tool execution:

```python

# Pseudocode for state tracking

def on_pre_tool_use(tool_name, parameters):

state = get_session_state()

# Update counters

state.tool_counts.total += 1

state.tool_counts[categorize(tool_name)] += get_weight(tool_name)

# Check for boundary markers

if is_boundary_marker(tool_name, parameters):

state.boundaries[get_boundary_type(tool_name, parameters)] += 1

state.timestamps.last_boundary = now()

# Update activity flags

update_activity_flags(state, tool_name, parameters)

# Evaluate suggestion opportunity

if should_suggest_compact(state):

return generate_suggestion(state)

return None # Allow tool to proceed

```

---

Default Threshold

The default threshold is 50 significant tool calls between logical boundaries.

This number is based on:

• Typical context window capacity for detailed work
• Average session complexity before context becomes "stale"
• Balance between interruption frequency and context quality

How to Configure Custom Thresholds

Thresholds can be configured in your project's .claude/settings.json:

```json

{

"skills": {

"strategic-compact": {

"thresholds": {

"default": 50,

"aggressive": 30,

"relaxed": 75,

"never": -1

},

"active_threshold": "default",

"boundary_weight": {

"task_completion": 0.5,

"commit": 0.3,

"phase_completion": 0.7

}

}

}

}

```

Different Thresholds for Different Scenarios

| Scenario | Threshold | Rationale |

|----------|-----------|-----------|

| Standard Development | 50 | Balanced for typical feature work |

| Complex Debugging | 75 | Need more context for issue tracking |

| Quick Fixes | 30 | Less context needed, faster cycles |

| Large Refactoring | 40 | Many files, context can get stale |

| Documentation | 60 | Mostly reading, less state to track |

| Plan Execution | Per-phase | Align with plan phase boundaries |

Dynamic Threshold Adjustment:

The skill can adjust thresholds based on detected activity:

```yaml

dynamic_rules:

- condition: "active_debugging == true"

adjustment: "+25"

reason: "Preserve debugging context"

- condition: "error_rate > 0.3"

adjustment: "+15"

reason: "Troubleshooting in progress"

- condition: "time_since_boundary > 30min"

adjustment: "-10"

reason: "Context likely getting stale"

```

---

The skill identifies optimal compaction moments by recognizing logical boundaries in your work.

When to Suggest Compact

#### After Completing a Phase/Task

Strong Signal - Task completion is the clearest boundary.

```yaml

trigger:

event: TaskUpdate

parameters:

status: completed

conditions:

- tool_count.significant >= threshold * 0.6

- time_since_last_suggestion > 10min

```

Suggestion appears after the task is marked complete, offering a natural pause point.

#### After Major Implementation Milestone

Strong Signal - Commits and successful builds indicate stable points.

```yaml

trigger:

event: Bash

command_pattern: "git commit"

result: success

conditions:

- tool_count.significant >= threshold * 0.7

- not pending_tasks_in_current_feature

```

#### Before Starting New Feature

Medium Signal - Beginning new work is a good reset point.

```yaml

trigger:

event: TaskUpdate

parameters:

status: in_progress

conditions:

- previous_task_completed

- feature_boundary_detected

- tool_count.significant >= threshold * 0.5

```

#### When Context is About to Overflow

Warning Signal - Proactive suggestion before forced compaction.

```yaml

trigger:

event: any

conditions:

- estimated_context_usage > 0.8

- tool_count.significant >= threshold * 0.9

priority: high

```

When NOT to Suggest Compact

#### During Active Debugging

```yaml

suppress_when:

- recent_error_count > 0

- last_tool_was: [Read, Grep, Glob] # Investigating

- pattern_detected: "debug_cycle"

- task_subject_contains: ["debug", "fix", "investigate"]

```

Rationale: Debugging requires building up mental models and context. Compacting mid-debug loses the trail of investigation.

#### During Active Implementation

```yaml

suppress_when:

- uncommitted_changes: true

- last_tools_sequence: [Edit, Edit, Edit] # Active coding

- time_since_last_edit < 5min

- test_failures_unresolved: true

```

Rationale: Mid-implementation compaction risks losing track of partial work and the reasoning behind changes.

#### Other Suppression Conditions

```yaml

suppress_when:

- last_suggestion < 10min_ago # Avoid nagging

- user_deferred_recently: true # Respect user choice

- critical_operation_in_progress: true

- rollback_or_revert_active: true

```

---

When to Accept Compact Suggestion

Accept when:

• You've just completed a logical unit of work
• The suggestion aligns with a natural pause in your workflow
• You're about to context-switch to a different feature/area
• You've made a commit and tests are passing
• You notice responses are getting slower or less accurate

When to Defer

Defer when:

• You're in the middle of tracking down a bug
• You have uncommitted changes you're still working on
• You're about to run a critical command that needs context
• You're iterating on a specific piece of code
• The current task is almost complete (< 5 minutes remaining)

How to Preserve Context Before Compact

Before accepting a compaction suggestion, ensure critical context is preserved:

1. Check for uncommitted work:

```bash

git status

git diff --stat

```

1. Review active tasks:

```

TaskList to see pending work

```

1. Document decision points:

- Any architectural decisions made

- Reasoning behind non-obvious choices

- Known issues or TODOs discovered

1. Capture current position:

- What file/function you're working in

- What the next step should be

- Any blockers or dependencies

Using context-saver Skill Before Compacting

The strategic-compact skill integrates with the context-saver skill to preserve session state:

```yaml

compact_workflow:

1. Detect compaction opportunity

2. Check if context-saver is available

3. If available:

- Invoke context-saver with current session state

- Wait for context file creation

- Include context file path in compact summary

4. Present compaction suggestion with preserved context reference

5. If accepted:

- Perform compaction

- New session starts with context file reference

```

Integration Example:

```

[Strategic Compact Suggestion]

Session Status:

• Tool calls: 67 (threshold: 50)
• Last boundary: Task "Implement auth flow" completed 5 min ago
• Current state: Between tasks, no active debugging

Recommendation: Good time to compact

Before compacting, I'll save your context:

> Invoking context-saver skill...

> Context saved to: .claude/contexts/session-2024-01-15-auth-impl.md

You can reference this context in your next session with:

> "Continue from .claude/contexts/session-2024-01-15-auth-impl.md"

Accept compaction? [Y/n]

```

---

Example hooks.json Configuration

Create or update .claude/hooks.json in your project:

```json

{

"hooks": {

"PreToolUse": [

{

"name": "strategic-compact-monitor",

"skill": "strategic-compact",

"enabled": true,

"priority": 10,

"config": {

"threshold": 50,

"mode": "suggest",

"integrate_context_saver": true,

"suppress_during": [

"debugging",

"active_implementation",

"rollback"

],

"boundary_events": [

"task_completion",

"git_commit",

"phase_transition",

"feature_boundary"

]

}

}

]

}

}

```

Configuration Options

| Option | Type | Default | Description |

|--------|------|---------|-------------|

| threshold | number | 50 | Tool calls before suggesting |

| mode | string | "suggest" | "suggest", "warn", or "silent" |

| integrate_context_saver | boolean | true | Auto-invoke context-saver |

| suppress_during | array | [...] | Activity types to suppress during |

| boundary_events | array | [...] | Events that count as boundaries |

| min_interval | number | 600 | Min seconds between suggestions |

| dynamic_threshold | boolean | true | Adjust threshold based on activity |

How to Enable/Disable

Enable for a project:

```bash

# Add to project settings

echo '{"skills": {"strategic-compact": {"enabled": true}}}' > .claude/settings.json

```

Disable temporarily:

```

/strategic-compact disable

```

Disable for session:

```json

{

"hooks": {

"PreToolUse": [

{

"name": "strategic-compact-monitor",

"enabled": false

}

]

}

}

```

Integration with Claude Code

The skill integrates with Claude Code's hook system:

```

Claude Code Session

│

▼

PreToolUse Hook

│

▼

strategic-compact-monitor

│

├── Update counters

├── Check boundaries

├── Evaluate conditions

│

▼

[Suggestion or Pass-through]

│

▼

Tool Execution

│

▼

PostToolUse (optional logging)

```

---

Clear, Non-Intrusive Suggestions

Suggestions should be informative but not disruptive:

```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Context Compaction Suggested

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Session Metrics:

Tool calls: 72 significant (threshold: 50)

Session time: 45 minutes

Last boundary: Task completed 3 min ago

Boundary Detected:

Task "Add user authentication" marked complete

Git commit: "feat: implement JWT auth flow"

No pending changes or active debugging

Recommendation: GOOD TIME TO COMPACT

Options:

[1] Compact now (will invoke context-saver first)

[2] Defer for 15 minutes

[3] Defer until next boundary

[4] Dismiss (don't suggest again this session)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

```

Include Current Tool Count

Always show the current state so users understand why the suggestion appeared:

```

Tool Activity Summary:

- Edits: 23 files modified

- Reads: 45 files examined

- Commands: 18 bash operations

- Searches: 12 grep/glob operations

Weighted Total: 72 (threshold: 50)

```

Include Reason for Suggestion

Be explicit about why this moment was chosen:

```

Why now?

✓ Task "Implement auth flow" completed

✓ Successful commit made

✓ All tests passing

✓ No uncommitted changes

✓ No active debugging session

This is a natural pause point in your workflow.

```

Minimal Mode (for experienced users)

```

[Compact? 72/50 calls | Task done | Clean state] Y/n/defer

```

---

Per-Project Thresholds

Different projects may need different thresholds:

```json

{

"projects": {

"large-monorepo": {

"threshold": 40,

"reason": "Many files, context gets stale quickly"

},

"focused-library": {

"threshold": 75,

"reason": "Smaller scope, more context helpful"

},

"debugging-session": {

"threshold": 100,

"reason": "Need extensive context for investigation"

}

}

}

```

Custom Boundary Definitions

Define project-specific boundaries:

```json

{

"custom_boundaries": {

"migration_complete": {

"trigger": "Bash",

"pattern": "npm run migrate",

"success_required": true,

"weight": 0.8

},

"deploy_staging": {

"trigger": "Bash",

"pattern": "deploy.*staging",

"weight": 1.0

}

}

}

```

Integration with Other Skills

The strategic-compact skill can coordinate with:

• context-saver: Automatic context preservation before compact
• implement-phase: Phase completion as boundary markers
• create-plan: Plan phase transitions as boundaries
• code-review: Review completion as boundary markers

```yaml

skill_integration:

context-saver:

invoke_before_compact: true

pass_session_state: true

implement-phase:

listen_for: phase_complete

boundary_weight: 1.0

create-plan:

listen_for: plan_created

suggest_compact_after: true

```

---

Suggestions Too Frequent

Increase threshold or add suppression conditions:

```json

{

"threshold": 75,

"min_interval": 900

}

```

Suggestions Never Appear

Check that:

1. Hook is enabled in .claude/hooks.json
2. Threshold is set appropriately
3. Skill is not permanently suppressed

Context Not Being Saved

Ensure context-saver skill is available:

```bash

ls -la skills/context-saver/SKILL.md

```

Boundaries Not Detected

Add custom boundary patterns for your workflow:

```json

{

"custom_boundaries": {

"my_workflow_step": {

"trigger": "Bash",

"pattern": "your-command-pattern"

}

}

}

```

---

The strategic-compact skill transforms context compaction from an arbitrary interruption into a thoughtful workflow optimization. By monitoring session state, recognizing logical boundaries, and integrating with context preservation tools, it ensures that compaction happens at optimal moments without disrupting active work.

Key principles:

1. Suggest, don't force - Respect user workflow
2. Boundary-aware - Align with natural pause points
3. Context-preserving - Integrate with context-saver
4. Configurable - Adapt to different projects and preferences
5. Non-intrusive - Clear but minimal suggestions

Use this skill to maintain high-quality context throughout long sessions while avoiding the disruption of poorly-timed compaction.