jiten-singh-shahi/strategic-compact

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

| Phase Transition | Compact? | Why | |-----------------|----------|-----| | Org exploration -> Planning | Yes | Org metadata is bulky; plan is the distilled output | | Planning -> Apex implementation | Yes | Plan is saved to a file; free up context for code | | Apex implementation -> LWC work | Yes | Clear Apex context for unrelated frontend work | | Apex implementation -> Apex testing | Maybe | Keep if tests reference recent code; compact if switching focus | | Debugging -> Next feature | Yes | Debug traces pollute context for unrelated work | | Mid-implementation | No | Losing class names, field APIs, and partial state is costly | | After a failed deployment | Yes | Clear the dead-end reasoning before trying a new approach | | Trigger work -> Flow work | Yes | Different domains with different context needs |

What Survives Compaction

Understanding what persists helps you compact with confidence:

| Persists | Lost | |----------|------| | CLAUDE.md instructions | Intermediate reasoning and analysis | | Task list (if saved to a file) | File contents you previously read | | Project-level settings and rules | Multi-step conversation context | | Git state (commits, branches) | Tool call history and counts | | Files on disk | Nuanced user preferences stated verbally | | Org metadata on disk | SOQL query results from exploration |

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%+:

| Trigger Keywords | Skill | Load When | |---------|-------|-----------| | "test", "tdd", "coverage" | sf-apex-testing | User mentions testing | | "security", "sharing", "crud" | sf-security | Security-related work | | "deploy", "scratch org", "ci" | sf-deployment | Deployment context | | "soql", "query", "selectivity" | sf-soql-optimization | Query optimization | | "trigger", "handler", "fflib" | sf-trigger-frameworks | Trigger development |

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)

| Content Type | Approximate Tokens | Notes | |-------------|-------------------|-------| | CLAUDE.md | 2-5K | Always loaded | | Each rule file | 500-2K | All active rules loaded | | Each loaded skill | 1-5K | Loaded on demand | | Apex class (500 lines) | 3-5K | When Read tool is used | | LWC component (3 files) | 2-4K | HTML + JS + CSS | | SOQL query result (100 rows) | 2-8K | Depends on field count | | Test output (full suite) | 5-15K | Use --result-format human to reduce | | Debug log (1000 lines) | 8-15K | Filter with --log-level WARN |

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