strategic-compact

name	strategic-compact
description	Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.

Strategic Compact Skill

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

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 (Edit/Write) 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

Add to your ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "tool == \"Edit\" || tool == \"Write\"",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/strategic-compact/suggest-compact.sh"
      }]
    }]
  }
}

Configuration

Environment variables:

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

Best Practices

1. Compact after planning - Once plan is finalized, 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

---

Sudocode Integration

Compaction Boundaries in Sudocode Workflow

The sudocode workflow has natural compaction boundaries:

Phase 1: Capture (Spec)     ← Compact AFTER creating spec
Phase 2: Plan (Issue)       ← Compact AFTER planning issues
Phase 3: Execute (Tasks)    ← DON'T compact mid-implementation
Phase 4: Close (Feedback)   ← Compact AFTER closing issue

Recommended Compaction Points

Good times to compact:

1. After spec creation

   • Spec is persisted in .sudocode/specs/
   • Context can be reloaded with show_spec
   • Compact to start fresh for planning

2. After issue planning

   • Issues are persisted with relationships
   • ready will show what to work on
   • Compact before implementation

3. After closing an issue

   • Work is complete and documented
   • Feedback is attached to spec
   • Fresh context for next issue

Bad times to compact:

1. Mid-implementation

   • Lose context about current approach
   • May duplicate work or miss edge cases

2. Before providing feedback

   • Need context to write good feedback
   • Wait until feedback is submitted

3. While debugging

   • Investigation context is crucial
   • Compact after resolution

Sudocode-Aware Suggestion

Update the compaction suggestion to check sudocode state:

# In suggest-compact.sh, add check:
CURRENT_ISSUE=$(sudocode issue list --status=in_progress --format=count 2>/dev/null)

if [ "$CURRENT_ISSUE" -gt 0 ]; then
  echo "⚠️ Issue in progress - consider completing before compact"
else
  echo "✓ No issue in progress - safe to compact"
fi

Context Preservation Across Compaction

Since sudocode persists context, after compaction you can restore:

1. /compact
2. ready                    # See available work
3. show_issue <id>          # Reload issue context
4. show_spec <linked-spec>  # Reload requirements
5. Continue implementation

Key context survives in:

• .sudocode/specs/ - All spec content
• .sudocode/issues/ - Issue state and relationships
• Feedback - Attached to specs
• Git history - Code changes