Strategic Compact Skill

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

When to Use

• When running long Salesforce development sessions that approach context limits (200K+ tokens)
• When transitioning between distinct development phases (org exploration -> planning -> implementation)
• When switching between unrelated Salesforce domains (Apex -> LWC -> Flow configuration)
• After completing a major milestone (feature shipped, deployment succeeded) before starting new work
• When responses slow down or become less coherent due to context pressure

Why Strategic Compaction?

Auto-compaction triggers at arbitrary points:

• Often mid-task, losing important context about org structure or governor limits
• No awareness of logical task boundaries
• Can interrupt complex multi-step Salesforce operations (deploy pipeline, test runs)

Strategic compaction at logical boundaries:

• After org exploration, before implementation — Compact metadata/schema context, keep implementation plan
• After completing a feature — Fresh start for next feature
• Before switching domains — Clear Apex context before LWC work

How It Works

The suggest-compact.js 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

Compaction Decision Guide

What Survives Compaction

Understanding what persists helps you compact with confidence:

Best Practices

1. Compact after planning — Once plan is finalized and saved to a file, compact to start fresh
2. Compact after debugging — Clear error-resolution context before continuing
3. Don't compact mid-implementation — Preserve context for related Apex/LWC changes
4. Read the suggestion — The hook tells you when, you decide if
5. Write before compacting — Save important context (org structure, field APIs) to files or memory before compacting
6. Use /compact with a summary — Add a custom message: /compact Focus on implementing trigger handler next

Salesforce-Specific Tips

• Save org metadata before compacting — Object/field lists, record type IDs, profile names
• Save governor limit findings — If you discovered limit issues, document them first
• Save deployment results — Deployment errors/warnings should be saved before compacting
• Keep test results accessible — Write failing test details to a file before compacting

Token Optimization Patterns

Trigger-Table Lazy Loading

Note: This is an aspirational optimization pattern -- SCC currently loads skills based on frontmatter triggers, not a runtime lazy-loading table.

Instead of loading full skill content at session start, use a trigger table that maps keywords to skill paths. Skills load only when triggered, reducing baseline context by 50%+:

Context Composition Awareness

Monitor what consumes your context window:

• CLAUDE.md files — Always loaded, keep lean
• Loaded skills — Each skill adds 1-5K tokens; SCC has 58 skills
• Conversation history — Grows with each exchange
• Tool results — File reads, SOQL results, test output add bulk
• Rules — Always-on guidelines consume baseline context

Duplicate Instruction Detection

Common sources of duplicate context in SCC projects:

• Skills that repeat CLAUDE.md instructions
• Multiple skills covering overlapping domains (e.g., security guidance in both sf-security and sf-governor-limits skills)
• Agent descriptions that duplicate skill content

Save-Before-Compact Examples

Before compacting, write critical context to files so it survives:

Save Org Metadata

# Save field list for target object
sf sobject describe --sobject Account --json > .claude/org-context/account-fields.json

# Save record type IDs
sf data query --query "SELECT Id, Name, DeveloperName FROM RecordType WHERE SobjectType = 'Account'" --json > .claude/org-context/record-types.json

Save Investigation Findings

<!-- .claude/session-notes.md — write before compacting -->
## Governor Limit Findings (2026-03-24)
- AccountTriggerHandler.cls line 45: SOQL in loop (CRITICAL)
- OrderService.cls: 3 DML statements could be combined (MEDIUM)
- Coverage: AccountService 82%, OrderService 61% (needs work)

## Deployment Blockers
- Missing field: Account.Risk_Category__c not in target org
- Flow "Auto Case Assignment" references deleted queue

Save Test Results

<!-- .claude/test-results.md -->
## Last Test Run
- 142/145 passing
- Failed: OrderServiceTest.shouldHandleBulkUpdate (NPE at line 89)
- Failed: CaseTriggerTest.shouldEscalateHighPriority (assertion at line 34)
- Failed: IntegrationTest.shouldCallExternalAPI (callout not mocked)
- Coverage: 78% org-wide

Multi-Session Continuity

For work spanning multiple sessions, use compact + session commands:

Session 1: Plan feature
  +-- /save-session -> saves plan, org context, findings
  +-- /compact -> clean slate

Session 2: Implement Apex
  +-- /resume-session -> restores plan context
  +-- [implement Apex classes]
  +-- /save-session -> saves implementation state
  +-- /compact

Session 3: Implement LWC + Deploy
  +-- /resume-session -> restores implementation context
  +-- [build LWC, deploy, verify]

Large Project Handling

For projects with 100K+ lines of code:

• Don't read entire codebase — Use Grep/Glob to find specific files
• Use codemaps — deep-researcher agent creates navigable index without loading full files
• Compact aggressively between features — Each feature is a fresh context
• Save architecture notes to files — Don't rely on conversation memory for class relationships
• Use agents for parallel investigation — Subagents have their own context windows

Approximate Token Costs (as of the current API version per @../_reference/API_VERSIONS.md — may vary with model and encoding)

Related

• suggest-compact.js hook — Automatic compaction suggestions
• /save-session and /resume-session — State that survives compaction
• sf-debugging skill — Debug context preservation
• learning-engine agent — Extracts patterns before session ends