Compaction Strategies

Frequent Intentional Compaction (FIC)

The FIC methodology, developed for managing AI coding agents on large codebases, is the most rigorous approach to context management. Its core principle: design entire workflows around context management, targeting 40-60% utilization.

The FIC Workflow

1. Research Phase (target: 60% max utilization)

   Use sub-agents for all exploration. The main context receives only compressed summaries.

   Use sub-agents to research:
   1. How the payment processing pipeline works
   2. Which files handle Stripe webhook events
   3. What the test infrastructure looks like
   
   Save findings to .sdlc/research/payment-pipeline.md

   Compact after research: Preserve the research summary, discard sub-agent coordination overhead.

2. Planning Phase (target: 50% max utilization)

   Work from the research document, not from memory. Create a detailed plan.

   Based on .sdlc/research/payment-pipeline.md,
   create an implementation plan for adding PayPal support.
   Save to .sdlc/plans/paypal-integration.md

   Compact after planning: Preserve the plan reference, discard planning discussion.

3. Implementation Phase (target: 60% max utilization)

   Execute from the plan file. For complex implementations, compact between sub-steps.

   Follow .sdlc/plans/paypal-integration.md, starting at step 1.
   Use TDD for each step.

   For multi-step implementations, compact your context after each verified step. See Tool Configuration Reference for your tool’s compact command.

   Compact your context. Step 1 complete and verified. Preserve: plan progress
   (steps 1-3 done, step 4 next), modified files list, test results.

FIC Compaction Artifacts

When compacting, produce a structured summary:

## Compaction Summary
### Goal
Adding PayPal support to payment pipeline

### Progress
- [x] Step 1: PayPal client wrapper (src/clients/paypal.ts)
- [x] Step 2: Webhook handler (src/api/webhooks/paypal.ts)
- [x] Step 3: Payment service integration (src/services/payments.ts)
- [ ] Step 4: Refund flow
- [ ] Step 5: Integration tests

### Modified Files
- src/clients/paypal.ts (new)
- src/api/webhooks/paypal.ts (new)
- src/services/payments.ts (modified)
- src/types/payment.ts (modified)

### Key Decisions
- Using PayPal REST API v2 (not NVP)
- Webhook signature verification via paypal.verifySignature()
- Idempotency keys stored in Redis (same as Stripe)

### Blockers
None currently

Strategy Comparison

Strategy	When to Use	Pros	Cons
Full clear/reset	Between unrelated tasks	Cleanest context possible	Loses all session state
Manual compact	Between phases of same task	Preserves key decisions	Some information loss
Selective compaction	Targeted cleanup	Precise control	Manual overhead
Auto-compaction (95%)	Never by choice	Safety net	Too late — quality already degraded
Sub-agent isolation	During exploration	No main context pollution	Communication overhead
FIC workflow	Complex, multi-phase tasks	Optimal quality throughout	Requires discipline

The Compaction Tuning Approach

When customizing compaction, follow this priority:

1. Maximize recall first — ensure all relevant information is captured
2. Then improve precision — eliminate superfluous content

The “low-hanging fruit” is clearing tool call results from deep in message history. File reads and command outputs from completed steps rarely need to be retained verbatim.

Structured Note-Taking

For tasks that span many compaction cycles, maintain a persistent scratchpad:

Before starting, create NOTES.md to track progress.
After each major step, update NOTES.md with:
- What was accomplished
- What files were changed
- Any issues encountered
- What comes next

Consult NOTES.md after any compaction event.

Tip

The real-world example: an AI agent playing Pokemon maintained precise tallies across thousands of steps — tracking objectives, discovered regions, and combat strategies — enabling multi-hour coherence across context resets. The same technique works for complex coding tasks.

Key Takeaways

• Never rely on auto-compaction — it triggers too late (95%)
• Target 40-60% utilization for complex reasoning tasks
• Compact between workflow phases with explicit preservation instructions
• Use FIC for multi-phase tasks: research → plan → implement with compaction between each
• Maintain scratchpad files for information that must survive multiple compactions
• Use sub-agents to prevent exploration from polluting the main context
• These strategies apply across AI coding agents — Claude Code, Cursor, Copilot Workspace all benefit from deliberate context management