OpenAgentsControl/.opencode/context/core/context-system/guides/compact.md

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 setCount(count + 1)}> Clicked {count} times

**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**:

markdown 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**:

markdown 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

markdown ❌ "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

markdown ❌ "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

markdown ❌ 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

markdown ❌ "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

<rule id="thirty_second_rule" enforcement="strict">
  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
</rule>

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

---

## Compression Examples

### Before: 150 lines

markdown

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

markdown

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:

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 ```

---

Related

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