Context Compression & Archiving

As your product repo grows, older epics, stories, and meeting notes accumulate. This creates two problems:

LLM context bloat – Thousands of files make it harder for the model to find relevant information.
Human cognitive load – New team members wade through years of history.

This guide explains how to use context compression and archiving to keep the working set small while preserving full history in Git.

Core Principles

Compression is Lossy but Regeneratable

Context files are LLM-optimized, human-readable summaries that prioritize:

Current state
Recent decisions
Active risks

They are regeneratable from source files – not the other way around. Original files (meetings, epics, stories, research) are the canonical source of truth. Context files are derived views.

Originals Are Never Deleted

Archive old files, don't remove them. This preserves:

Git history (Git log still shows all changes)
Auditability (you can trace decisions back to their origin)
Reversibility (if you need to understand a past decision, it's still there)

LLMs Should Prefer Context + Current Over Archive

Configure your IDE and prompts to:

Include: active context files (*-context.md), strategy, evidence, non-archived epics/stories
Exclude by default: /archive folders
Read archive only when explicitly requested (e.g., "show me the history of registration")

Folder Structure with Context Files

For any busy folder, add a context file and an archive subfolder:

/delivery
  delivery-context.md
  epic-003-checkout/
    epic-003-checkout.md
    story-ep003-001.md
    story-ep003-002.md
  epic-004-payments/
    epic-004-payments.md
  /archive
    epic-001-legacy-registration.md
    epic-002-old-onboarding.md
    stories/
      story-ep001-001.md
      story-ep001-002.md

/meetings
  meetings-context.md
  2025-12-15-roadmap-planning.md
  2025-12-08-design-review.md
  /archive
    2023-Q4-planning.md
    2024-Q1-retro.md

/discovery
  discovery-context.md
  insights.md
  research-log.md
  /archive
    research-2023.md
    user-interviews-early.md

Context Files Live at Folder Level

Place *-context.md at the root of the folder it summarizes:

delivery/delivery-context.md – summarizes /delivery
meetings/meetings-context.md – summarizes /meetings
discovery/discovery-context.md – summarizes /discovery

Or use domain-specific state files:

context/registration-state.md – current behavior of registration
context/billing-state.md – current billing implementation

Both patterns work. Colocating with the folder is simplest.

Context File Structure

A context file should be highly structured and skimmable. Use this template:

# [Folder] Context – Updated [YYYY-MM-DD]

## Status Summary
- [1–2 sentences on current state]
- Key active work: [epic names or themes]
- Recent changes: [link to PR or decision]

## Active Epics & Priorities
- **EP-003: Checkout Redesign** (In Progress)
  - Acceptance: All stories merged; awaiting QA
  - Owner: [name]
  - Related: [other epics or strategic goals]
  - Source: strategy-section-link

- **EP-004: Payments** (Ready)
  - Scope: Add Stripe integration, support 3+ payment methods
  - Risks: Legacy gateway compatibility
  - Owner: [name]
  - Source: strategy-section-link

## Recent Decisions & Learnings
- **Decision:** Deprecate in-app password reset (2025-12-08)
  - Rationale: 80% of users prefer email reset
  - Related: meetings/2025-12-08-design-review.md
  - Impact: Simplifies EP-003 scope

## Open Questions & Risks
- Q: Should we support legacy browsers for checkout?
  - Status: TBD (design review pending)
  - Owner: [PM/designer]

- R-01: Stripe integration delays (Medium likelihood, High impact)
  - Mitigation: Parallel Adyen implementation
  - Owner: [engineering lead]

## Archived Items
- Archived 2025-02-08: EP-001, EP-002 (legacy registration work)
  - Moved to: `/archive/epics/`
  - Reason: Shipped; no longer active

## Sources
- `/delivery/epic-003-*/` – Active epics
- `/delivery/epic-004-*/` – Active epics
- `product-strategy.md` – Strategic foundation
- `meetings/2025-12-*/` – Recent decisions

Key Properties

Prioritize recent over old – Lead with current epics and decisions.
Link heavily – Every epic, decision, and risk should link to its source.
Status matters – Show which epics are draft, active, or waiting.
Reason for archiving – If something moved to /archive, explain why.
Updated date – Record when the context file was last refreshed.

Compression Workflow

When your repo gets noisy, follow this workflow:

Step 1: Create or Update the Context File

Open or create [folder]/[folder]-context.md.
Read through non-archived files in the folder.
Summarize:
What's active and why
Recent decisions and learnings
Outstanding risks or open questions
Links to source files
Commit with message like: "Update delivery-context.md (2025-02-08)"

Example prompt for AI assistance:

"From /delivery, generate a delivery-context.md that: 1) Lists active epics with status and owner, 2) Summarizes recent decisions (from PR titles and epic updates), 3) Flags top 3 risks. Link every item back to source files."

Step 2: Identify Files to Archive

Look for files that are:

Shipped and no longer being developed
More than 6 months old with no recent activity
Resolved or deprecated
Not referenced in current epics or strategy

Example candidates:

epic-001-legacy-auth.md – shipped 12 months ago
meeting-2024-Q1-planning.md – decisions now stale
discovery/competitor-analysis-2023.md – outdated research

Step 3: Move to Archive

Create /archive/[subfolder]/ if needed.

Move old files:

mkdir -p delivery/archive/epics
git mv delivery/epic-001-legacy-auth/ delivery/archive/epics/epic-001-legacy-auth/
git mv meetings/2024-01-*.md meetings/archive/

Update the context file to note what was archived and when.
Commit with message: "Archive legacy epics and 2024 meeting notes"

Step 4: Instruct LLMs

In your .llm/ base instructions or prompts, add:

# Context Management

When working with this repo:
1. Always read `*-context.md` files first for orientation.
2. Explore non-archived files (active epics, recent stories, current meetings).
3. **Ignore `/archive` folders by default** – they're history, not current state.
4. Only read archive files if:
   - You're doing a historical audit
   - A current file explicitly references archived content
   - The user asks "what was the history of X?"

Examples

Example 1: Delivery Context After Compression

# Delivery Context – 2025-02-08

## Status
3 active epics (checkout redesign, payments, API v2). ~12 stories in progress. EP-001 and EP-002 (legacy registration) archived.

## Active Epics
- **EP-003: Checkout Redesign** – In Progress, 8/10 stories merged
- **EP-004: Payments** – Ready, awaiting refinement  
- **EP-005: API v2 (internal)** – Draft

## Recent Decisions
- 2025-02-08: Deprecate in-app password reset ([meeting](../meetings/2025-02-08-design-review.md))
- 2025-02-01: Stripe as primary gateway ([ADR](../architecture/payment-gateway-choice.md))

## Archived
- EP-001, EP-002 (registration): shipped 2024-Q4

Example 2: Meetings Context

# Meetings Context – 2025-02-08

## Recent Decisions (Last 30 Days)
1. **Deprecate in-app password reset** – Favors email reset (80% user preference)
2. **Stripe as primary payment gateway** – Best feature set; 2.9% fees acceptable
3. **Timeline slip**: EP-004 pushed 2 weeks due to legacy system dependencies

## Active Open Questions
- Q: Legacy browser support for checkout?
  - Owner: @design
  - Status: TBD
  - Next: Design review

## Upcoming
- 2025-02-15: Roadmap planning (quarterly)
- 2025-02-22: Stripe integration kickoff

## Sources
- meetings/2025-02-08-design-review.md
- meetings/2025-02-01-sync.md
- meetings/2025-01-25-payments-planning.md

When to Compress

Don't compress too early. Wait until:

You have 50+ files in a folder
More than 6 months of history
New team members struggle to find relevant files
LLM context feels cluttered

Compress regularly. Once you start:

Refresh context files monthly (or quarterly)
Archive files as they age
Keep /archive as the source of historical truth

Benefits

✓ Smaller LLM context – Focus on what's active
✓ Faster onboarding – New hires read context files, not 50 old epics
✓ Better search – Fewer irrelevant results
✓ Full history preserved – Git log still has everything
✓ Auditability – Can trace decisions to their source even if archived