Tutorial: Compaction-Resilient Projects

Long-running features inevitably hit context limits. This tutorial shows how to structure your project and workflow so nothing critical is lost when compaction occurs.

The Problem

Without preparation, compaction loses:

• Nuanced decisions made early in the session
• Exact file contents read earlier
• The reasoning behind architectural choices
• Progress on multi-step implementations
• Relationships between changes

The Solution: External Persistence

The key insight: anything that must survive compaction must exist outside the context window — in files, not in chat history.

Setting Up the Infrastructure

1. Create the .sdlc directory

   mkdir -p .sdlc/{specs,plans,research,progress}

2. Add compaction instructions to your agent configuration file

   Add the following to your agent configuration file:

   ## Compaction Instructions
   When compacting, always preserve:
   - References to active .sdlc/ files
   - The full list of modified files
   - Current step in any active plan
   - All test commands that have been run
   - Any architectural decisions made this session
   
   After compaction, re-read the active PROGRESS.md if one exists.

3. Create a progress tracking template

   .sdlc/progress/TEMPLATE.md:

   # Progress: [Feature Name]
   
   ## Status: [In Progress / Blocked / Complete]
   ## Started: [Date]
   
   ## Spec
   .sdlc/specs/[feature].md
   
   ## Plan
   .sdlc/plans/[feature].md
   
   ## Current Step
   Step [N] of [total]: [description]
   
   ## Completed Steps
   - [x] Step 1: [description] — [files modified]
   - [x] Step 2: [description] — [files modified]
   - [ ] Step 3: [description]
   
   ## Modified Files
   - src/path/to/file.ts (new/modified)
   - src/path/to/other.ts (modified)
   
   ## Decisions Made
   - Chose sliding window over fixed window because [reason]
   - Using Redis for distributed state because [reason]
   
   ## Blockers
   None / [Description of blocker]
   
   ## Next Action
   [What to do next when resuming]

The Compaction-Resilient Workflow

Starting a Feature

Create a progress tracker at .sdlc/progress/rate-limiting.md
using the template. We're implementing rate limiting based on
.sdlc/specs/rate-limiting.md with the plan at
.sdlc/plans/rate-limiting.md.

During Implementation

After each significant step:

Update .sdlc/progress/rate-limiting.md:
- Mark step 3 as complete
- Add src/middleware/rateLimit.ts to modified files
- Record decision: using lua scripts for atomic Redis operations
- Set next action: implement step 4 (test infrastructure)

After Compaction

When you notice compaction has occurred (or start a new session):

Read .sdlc/progress/rate-limiting.md to restore context.
Continue from the next action listed there.

The progress file contains everything needed to resume:

• Where you are in the plan
• What files have been modified
• What decisions were made and why
• What to do next

Completing a Feature

Mark .sdlc/progress/rate-limiting.md as complete.
Move it to .sdlc/progress/archive/ for reference.

Multi-Session Features

For features spanning multiple days or sessions, use named sessions if your tool supports them. See the Tool Configuration Reference for your tool’s session commands.

# Day 1: Start a named session for research
# Research phase, save to .sdlc/research/

# Day 2: Start a named session for planning
# Planning phase, save to .sdlc/plans/

# Day 3-4: Start a named session for implementation
# Implementation with progress tracking

Check your agent’s documentation for how to resume or switch between named sessions. Most tools provide a way to continue a previous session or select from recent history.

What Goes Where

Information	Storage Location	Survives
Active progress	.sdlc/progress/[feature].md	Everything
Feature specification	.sdlc/specs/[feature].md	Everything
Implementation plan	.sdlc/plans/[feature].md	Everything
Research findings	.sdlc/research/[topic].md	Everything
Code changes	Git commits	Everything
Session context	Context window	Only current session

Tip

The cost of maintaining progress files is tiny compared to the cost of losing context. A 30-second update after each step saves 15+ minutes of context reconstruction after compaction.

Testing Your Setup

1. Start a multi-step task
2. Complete 2-3 steps, updating progress
3. Clear your context or start a fresh session to simulate compaction (see Tool Configuration Reference)
4. Resume using only the progress file
5. Verify you can continue seamlessly

If step 4 works without confusion, your setup is compaction-resilient.