Context Compaction (Minimization)

Purpose: Compress verbose content into minimal viable information

Last Updated: 2026-01-06

The Compaction Process

Transform verbose explanations → core concepts following MVI principle.

Formula:

Verbose Content (100+ lines)
  ↓ Extract Core
Core Concept (1-3 sentences)
  ↓ Extract Key Points
Key Points (3-5 bullets)
  ↓ Extract Example
Minimal Example (<10 lines)
  ↓ Add Reference
Link to Full Docs
  ↓ Result
Compact File (<100 lines)

Compression Techniques

1. Extract Core Concept

From: Paragraphs of explanation To: 1-3 sentences capturing essence

Example:

BEFORE (verbose):
"React Hooks are a new addition to React 16.8 that let you use state 
and other React features without writing a class. They're functions that 
let you "hook into" React state and lifecycle features from function 
components. Hooks don't work inside classes — they let you use React 
without classes. You can also create your own Hooks to reuse stateful 
behavior between different components..."

AFTER (compact):
"Hooks let you use state and lifecycle in function components without 
classes. They're functions that hook into React features (useState, 
useEffect, etc)."

Rule: If you can't explain it in 3 sentences, you don't understand it yet. Simplify further.

2. Bulletize Key Points

From: Long paragraphs To: 3-5 bullet points

Example:

BEFORE:
"When using hooks, there are several important rules to follow. First, 
only call hooks at the top level of your function, never inside loops, 
conditions, or nested functions. Second, only call hooks from React 
function components or custom hooks. Third, hooks should be called in 
the same order every render..."

AFTER:
**Key Points**:
- Call hooks at top level only (not in loops/conditions)
- Call from function components or custom hooks only
- Must be called in same order every render
- Names should start with "use" (convention)

Rule: Each bullet = one key fact. No sub-bullets.

3. Minimize Examples

From: Full implementations To: Smallest working example (<10 lines)

Example:

BEFORE (50 lines):
import React, { useState, useEffect } from 'react'
import axios from 'axios'

function UserProfile({ userId }) {
  const [user, setUser] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    const fetchUser = async () => {
      try {
        setLoading(true)
        const response = await axios.get(`/api/users/${userId}`)
        setUser(response.data)
        setError(null)
      } catch (err) {
        setError(err.message)
        setUser(null)
      } finally {
        setLoading(false)
      }
    }
    
    fetchUser()
  }, [userId])
  
  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error}</div>
  if (!user) return <div>No user found</div>
  
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  )
}

AFTER (8 lines):
```js
const [count, setCount] = useState(0)

useEffect(() => {
  document.title = `Count: ${count}`
}, [count]) // Re-run when count changes

return <button onClick={() => setCount(count + 1)}>
  Clicked {count} times
</button>

Rule: Show the simplest case that demonstrates the concept. Link to full examples.

4. Replace Repetition with References

From: Same info repeated in multiple places To: Define once, reference with links

Example:

BEFORE:
# File A
Authentication uses JWT tokens. JWT tokens are JSON Web Tokens that...

# File B
For auth, we use JWT tokens. JWT tokens are JSON Web Tokens that...

# File C
The JWT token system (JSON Web Tokens) allows us to...

AFTER:
# concepts/jwt.md
"JWT (JSON Web Token) is a stateless authentication method..."

# Other files
See concepts/jwt.md for details.

Rule: Say it once in concepts/, reference everywhere else.

5. Convert Prose to Tables

From: Paragraphs listing things To: Scannable tables

Example:

BEFORE:
"There are several important lifecycle methods. componentDidMount runs 
after mounting, componentDidUpdate runs after updates, componentWillUnmount 
runs before unmounting..."

AFTER:
| Method | When It Runs |
|--------|--------------|
| componentDidMount | After mount |
| componentDidUpdate | After update |
| componentWillUnmount | Before unmount |

Rule: If listing >3 items, use a table or bullets.

Compaction Checklist

Before finalizing a context file:

Core concept is 1-3 sentences?
Key points are 3-5 bullets (no sub-bullets)?
Example is <10 lines of code?
No repeated explanations?
Reference link added for deep dive?
File is <200 lines total?
Can be scanned in <30 seconds?

If any "no", compress further.

Common Bloat Patterns

Bloat: Over-Explaining

❌ "This is important because it allows you to manage state in a more 
efficient way, which can lead to better performance and cleaner code..."

✅ "Manages state efficiently"

Bloat: Historical Context

❌ "Before React 16.8, we used class components. Then hooks were 
introduced to solve several problems with classes..."

✅ Skip history unless critical. Just explain current approach.

Bloat: Multiple Examples

❌ Example 1: useState with counter
   Example 2: useState with string
   Example 3: useState with object
   Example 4: useState with array...

✅ Show ONE simple example. Link to more.

Bloat: Implementation Details

❌ "The internal implementation uses a fiber architecture with a 
reconciliation algorithm that diffs the virtual DOM..."

✅ Skip internal details. Just show how to use it.

Target Line Counts

File Type	Target Lines	Max Lines
Concept	40-60	100
Example	30-50	80
Guide	60-100	150
Lookup	20-40	100
Error	50-80	150
README	40-60	100

Philosophy: If you hit max lines, split into multiple files or reference external docs.

The 30-Second Rule

Every context file must be scannable in <30 seconds.

If a developer can't grasp the core idea in 30 seconds:

File is too verbose
Concept is not well explained
Needs more compression

Test: Give file to someone unfamiliar. Can they explain it back in 30 seconds?

Compression Examples

Before: 150 lines

# Authentication System

Our authentication system is built on JSON Web Tokens (JWT), which 
is a standard for securely transmitting information between parties...

[100+ more lines of explanation, edge cases, examples, etc.]

After: 45 lines

# Concept: Authentication

**Core Idea**: JWT-based stateless auth. Token in httpOnly cookie, 
verified on every request.

**Key Points**:
- Token has userId + role claims
- Expires in 1 hour (refresh token for renewal)
- Stored in httpOnly cookie (XSS protection)
- Verified via middleware on protected routes

**Quick Example**:
```js
const token = jwt.sign({ userId: 123 }, SECRET, { expiresIn: '1h' })
res.cookie('auth', token, { httpOnly: true })

Reference: https://docs.company.com/auth Related: examples/jwt-auth.md, errors/auth-errors.md ```

mvi-principle.md - What MVI is
harvest.md - When to compact (during extraction)
templates.md - Standard formats

compact.md 7.5 KB Riwayat Mentahan

Context Compaction (Minimization)

The Compaction Process

Compression Techniques

1. Extract Core Concept

2. Bulletize Key Points

3. Minimize Examples

4. Replace Repetition with References

5. Convert Prose to Tables

Compaction Checklist

Common Bloat Patterns

Bloat: Over-Explaining

Bloat: Historical Context

Bloat: Multiple Examples

Bloat: Implementation Details

Target Line Counts

The 30-Second Rule

Compression Examples

Before: 150 lines

After: 45 lines

Related

compact.md 7.5 KB

Riwayat Mentahan