Documentation Size Management

Documentation Size Management is the practice of enforcing strict size limits on governance files to keep them focused, maintainable, and scannable by both humans and AI agents.

The Bloat Problem

Documentation tends to grow unbounded without limits:

Caution

What happens when docs get too large?

• Hard for humans to scan and update
• AI agents struggle to find relevant information
• Stale content accumulates
• Maintenance becomes burdensome

The solution: Enforce size limits. Every line of documentation must justify its existence.

---

File Size Limits

Cortex TMS enforces strict size limits on HOT files and relaxed limits on WARM files:

HOT Tier Limits (Strictly Enforced)

File	Max Lines	Why This Limit?
NEXT-TASKS.md	200 lines	One sprint maximum (1-2 weeks)
.github/copilot-instructions.md	100 lines	Critical rules only, no explanations

Why So Strict?

HOT files are read at the start of every AI session. If NEXT-TASKS.md grows to 500 lines, the AI wastes attention on outdated tasks every time.

200 lines keeps the sprint focused and scannable.

WARM Tier Limits (Recommended)

File	Max Lines	Why This Limit?
docs/core/PATTERNS.md	650 lines	Reference manual with quick-reference index
docs/core/DOMAIN-LOGIC.md	400 lines	Core rules + Maintenance Protocol
docs/core/ARCHITECTURE.md	500 lines	System design without implementation details
docs/core/GIT-STANDARDS.md	250 lines	Git conventions + commit standards
docs/core/GLOSSARY.md	200 lines	Terminology definitions

Tip

WARM files are read on demand, so limits can be higher. But bloat still reduces usefulness—a 2,000-line PATTERNS.md file is hard for AI (and humans) to navigate.

COLD Tier Limits

No limits. Archive files can grow indefinitely—AI agents ignore them unless explicitly asked.

---

Why Size Limits Matter

Example: The Bloated NEXT-TASKS.md

Let’s compare two projects:

❌ Project A: No Size Limits

# NEXT-TASKS.md (850 lines)

## Q1 2026 Tasks
- [ ] 50 tasks planned for January-March
...

## Q2 2026 Tasks
- [ ] 60 tasks planned for April-June
...

## Q3 2026 Tasks
- [ ] 70 tasks planned for July-September
...

## Completed Tasks (2025)
- [x] 100 tasks from last year
...

AI behavior:

• Gets confused about current priority
• References completed tasks as if they’re active
• Asks “Which task should I work on?” repeatedly

✅ Project B: With Size Limits

# NEXT-TASKS.md (180 lines)

## Active Sprint: User Authentication
**Why this matters**: Mobile app needs secure API access

- [ ] JWT token generation
- [ ] Token validation middleware
- [ ] Refresh token rotation
...

AI behavior:

• Immediately understands current focus
• Stays on task without prompting
• Follows established patterns from WARM tier

Result: Focused docs = better AI behavior and easier maintenance

---

Enforcement Strategies

1. Manual Review

Before archiving a task, check file size:

wc -l NEXT-TASKS.md
# Output: 185 NEXT-TASKS.md

If approaching 200 lines → Archive completed tasks or move backlog items to FUTURE-ENHANCEMENTS.md.

2. Automated Validation

Use the Cortex TMS CLI:

cortex-tms validate --strict

Output:

✓ NEXT-TASKS.md (185 lines) - Under limit
✗ copilot-instructions.md (120 lines) - EXCEEDS LIMIT (max 100)

Recommendations:
- Move detailed examples to docs/core/PATTERNS.md
- Keep only critical rules in copilot-instructions.md

3. Pre-Commit Hooks

Add a git hook to prevent oversized commits:

.git/hooks/pre-commit

#!/bin/bash
NEXT_TASKS_LINES=$(wc -l < NEXT-TASKS.md)

if [ $NEXT_TASKS_LINES -gt 200 ]; then
  echo "❌ NEXT-TASKS.md exceeds 200 lines ($NEXT_TASKS_LINES lines)"
  echo "Archive completed tasks before committing"
  exit 1
fi

echo "✓ NEXT-TASKS.md size OK ($NEXT_TASKS_LINES lines)"

---

What to Do When You Hit the Limit

HOT Files: Archive or Move

When NEXT-TASKS.md approaches 200 lines:

Archive Completed Tasks

Move finished tasks to docs/archive/sprint-YYYY-MM.md

# Before: 195 lines
# After:  120 lines

Move Backlog to FUTURE

Move low-priority tasks to FUTURE-ENHANCEMENTS.md

# Move "nice to have" tasks out of current sprint

Break Down Large Tasks

Split 50-line epics into smaller increments

# Instead of 1 huge task, create 5 focused ones

WARM Files: Split or Summarize

When docs/core/PATTERNS.md exceeds 650 lines:

Option 1: Split into Multiple Files

docs/core/
├── PATTERNS.md           (index + core patterns)
├── PATTERNS-FRONTEND.md  (React/Vue patterns)
├── PATTERNS-BACKEND.md   (API patterns)
└── PATTERNS-DATA.md      (Database patterns)

Option 2: Create Quick-Reference Index

PATTERNS.md

## Quick Reference
| Pattern | Line | Use When |
|---------|------|----------|
| Auth Pattern | 45 | Implementing login/signup |
| API Pattern | 120 | Building REST endpoints |
| ...

## Detailed Patterns
### Auth Pattern
...

AI can scan the index, jump to the relevant section.

---

Context Budget Best Practices

1. Use Canonical Links, Not Duplication

Bad (wastes context):

## Button Pattern

[300 lines of duplicated code from Button.tsx]

Good (saves context):

## Button Pattern

**Canonical Example**: `src/components/Button.tsx:15`

**Key Rules**:
- Use `cva` for variant composition
- Support `size`, `variant`, `disabled` props

Tip

Duplication wastes space and causes drift. Canonical links stay accurate and keep docs focused.

2. Keep Examples Minimal

Bad:

## JWT Authentication

Here's a complete implementation:
[500 lines of code]

Good:

## JWT Authentication

**Canonical Implementation**: `src/middleware/auth.ts`

**Key Points**:
- Use RS256 (not HS256)
- Set 15-minute expiry
- Include user_id and role in payload

**Example**:
```typescript
const token = jwt.sign({ user_id, role }, privateKey, {
  algorithm: 'RS256',
  expiresIn: '15m'
});

### 3. Archive Aggressively

**Rule of thumb**: If you haven't referenced it in 2 months, archive it.

Historical context is valuable, but it's **COLD** context. Keep it in `docs/archive/`, not in files AI reads regularly.

### 4. Prefer Bullet Points Over Prose

**Bad** (verbose):
```markdown
When you are implementing authentication, you should make sure
that you are using the RS256 algorithm instead of HS256 because
RS256 is more secure and uses asymmetric keys which are better
for distributed systems where you can't share a secret safely.

Good (concise):

- Use RS256 (not HS256) for JWT signing
- Why: Asymmetric keys are safer for distributed systems

Benefit: More concise and scannable for both humans and AI.

---

Context Budget Violations

Common Violations

Even teams that understand context budgets sometimes violate them accidentally.

Violation 1: “Just One More Task”

Mistake: Adding tasks to NEXT-TASKS.md without removing completed ones

Impact: File grows from 180 → 220 → 300 lines over 2 months

Fix: Archive completed tasks immediately after marking ✅ Done

Violation 2: Documenting Implementation Details

Mistake: Copying entire source files into PATTERNS.md “for reference”

Impact: PATTERNS.md grows to 2,000 lines

Fix: Use canonical links. Provide rules, not implementations.

Violation 3: Historical Changelog in HOT

Mistake: Keeping 2 years of changelog in CHANGELOG.md at project root (HOT tier)

Impact: AI reads 5,000 lines of irrelevant history every session

Fix: Keep only current version in HOT. Archive old versions to docs/archive/v1.0-CHANGELOG.md (COLD).

---

Benefits of Context Budget Discipline

Better AI Focus

Lean docs keep AI focused on what matters. Less time scanning, more time coding.

Easier Maintenance

Smaller files are easier for humans to review, update, and keep current.

Reduced Staleness

Focused docs are more likely to stay up-to-date with code changes.

Enforced Clarity

Size limits force concise writing. No room for fluff or redundancy.

---

Enforcement Checklist

Before marking a task ✅ Done, verify:

• NEXT-TASKS.md is under 200 lines
• copilot-instructions.md is under 100 lines
• WARM files are under their recommended limits
• Completed tasks archived to docs/archive/
• Backlog items moved to FUTURE-ENHANCEMENTS.md

Tool: Run cortex-tms validate --strict to check automatically.

---

Next Steps

Now that you understand context budgets:

• Learn about Tiered Memory for the bigger picture
• Explore Zero-Drift Governance for validation
• Read about Truth Syncing for maintenance workflows

Start Small

Don’t try to enforce all limits at once. Start with NEXT-TASKS.md (most impactful), then gradually apply limits to other files.