MVI Principle (Minimal Viable Information)

Purpose: Extract only core concepts, not verbose explanations

Last Updated: 2026-01-06

Core Idea

Extract the minimum information needed for an AI agent to understand and use a concept:

Core concept (1-3 sentences)
Key points (3-5 bullets)
Minimal working example
Reference link to full docs

Goal: Scannable in <30 seconds. Reference full docs, don't duplicate them.

The Formula

Core Concept (1-3 sentences)
  ↓
Key Points (3-5 bullets)
  ↓
Quick Example (5-10 lines)
  ↓
Reference Link (full docs)
  ↓
Related Files (cross-refs)

What to Extract ✅

Core definitions - What it is (1-3 sentences)
Key properties - Essential characteristics (3-5 bullets)
Minimal example - Simplest working code (5-10 lines)
Common patterns - How it's typically used (2-3 bullets)
Critical gotchas - Must-know issues (1-2 bullets)
Reference links - Where to learn more

What to Skip ❌

Verbose explanations - Link to docs instead
Complete API docs - Summarize + reference
Implementation details - Show minimal example + reference
Historical context - Unless critical to understanding
Marketing content - Just the facts
Duplicate information - Say it once, reference elsewhere

Example: JWT Authentication

❌ Too Verbose (400+ lines)

# JWT Authentication

JSON Web Tokens (JWT) are an open standard (RFC 7519) that defines 
a compact and self-contained way for securely transmitting information 
between parties as a JSON object. This information can be verified and 
trusted because it is digitally signed. JWTs can be signed using a 
secret (with the HMAC algorithm) or a public/private key pair using RSA 
or ECDSA.

[... 400 more lines of explanation, examples, edge cases ...]

✅ MVI Compliant (~50 lines)

# Concept: JWT Authentication

**Core Idea**: Stateless authentication using JSON Web Tokens signed 
with a secret key. Token contains user data (payload) that server can 
trust because signature is verified.

**Key Points**:
- Token has 3 parts: header.payload.signature (Base64 encoded)
- Server verifies signature to trust payload without database lookup
- No session storage needed (stateless)
- Tokens expire (include `exp` claim)
- Store in httpOnly cookie or Authorization header

**Quick Example**:
```js
// Sign token
const token = jwt.sign(
  { userId: 123, role: 'admin' }, 
  SECRET_KEY, 
  { expiresIn: '1h' }
)

// Verify token
const decoded = jwt.verify(token, SECRET_KEY)
console.log(decoded.userId) // 123

Reference: https://jwt.io/introduction

Related:

examples/jwt-auth-example.md
guides/implementing-jwt.md
errors/auth-errors.md ```

File Size Limits

Concept files: max 100 lines
Example files: max 80 lines
Guide files: max 150 lines
Lookup files: max 100 lines
Error files: max 150 lines
README files: max 100 lines

Why: Forces brevity. If you need more, split into multiple files or reference external docs.

Validation Checklist

Before creating a context file, verify:

Core concept is 1-3 sentences?
Key points are 3-5 bullets?
Example is <10 lines of code?
Reference link is included?
File is <200 lines total?
Can be scanned in <30 seconds?

If any answer is "no", apply more compression.

structure.md - Where files go
compact.md - How to minimize
templates.md - Standard formats
creation.md - File creation rules

mvi.md 3.6 KB History Raw