context-window-stewardship

# Context Window Stewardship — APEX OS Standard

## Overview

Context window = a public good. Every token added degrades the space available
for reasoning. The goal is maximum signal per token. Context rot is real.

## The 3-Stage Loading Hierarchy (APEX OS Standard)

```
┌─────────────────────────────────────────────────────────────────────────┐
│ Stage 1 — Always in context (name + description only)                   │
│ → Agent uses this to decide WHETHER to load the skill                   │
│ → Hard limit: 2 lines. Never exceed.                                    │
├─────────────────────────────────────────────────────────────────────────┤
│ Stage 2 — Loaded on trigger (full SKILL.md body)                        │
│ → Loaded when skill description semantically matches the task           │
│ → Hard limit: 500 lines                                                 │
│ → Overflow → move to references/                                        │
├─────────────────────────────────────────────────────────────────────────┤
│ Stage 3 — Loaded on demand (references/, scripts/, assets/)             │
│ → Only when workflow explicitly needs them                              │
│ → Never inline large lookup tables or templates in SKILL.md            │
└─────────────────────────────────────────────────────────────────────────┘
```

## What Belongs Where

```
┌──────────────────────────────────┬──────────────────────────────────────┐
│ Content                          │ Location                             │
├──────────────────────────────────┼──────────────────────────────────────┤
│ Skill name + trigger description │ SKILL.md frontmatter (Stage 1)       │
│ Core workflow steps (≤500 lines) │ SKILL.md body (Stage 2)              │
│ Lookup tables > 20 rows          │ references/lookup.md (Stage 3)       │
│ Output format templates          │ assets/template.md (Stage 3)         │
│ Executable scripts               │ scripts/run.sh (Stage 3)             │
│ Session logs / project artifacts │ NOT IN SKILLS — wrong place          │
│ Personal documents               │ NOT IN SKILLS — wrong place          │
│ Large reference docs (>500 lines)│ NOT IN SKILLS — use RAG instead      │
└──────────────────────────────────┴──────────────────────────────────────┘
```

## Subagent Exception (CRITICAL)

```
┌─────────────────────────────────────────────────────────────────────────┐
│ Main agent:  Progressive disclosure applies.                            │
│              name+desc → SKILL.md → references on demand               │
│                                                                         │
│ ⚠️  Subagent:  ENTIRE SKILL.md is pre-loaded at dispatch.              │
│              No progressive disclosure. No on-demand loading.           │
│              Subagents do NOT inherit parent skills.                    │
│              Skills must be explicitly assigned to each subagent.       │
└─────────────────────────────────────────────────────────────────────────┘
```

## GSD's Solution to Context Rot

GSD (get-shit-done, `gsd-build/get-shit-done`) solves context rot by running
each plan in a **fresh 200k context subagent**. The orchestrator stays lean.

```
┌──────────────────────────────────────────────────────────────────────┐
│ Pattern: Orchestrator stays lean, workers get fresh context          │
│                                                                      │
│  Main session (30-40% context)                                       │
│         │                                                            │
│         ├──→ Subagent A (200k fresh) → executes Plan 1 → commits   │
│         ├──→ Subagent B (200k fresh) → executes Plan 2 → commits   │
│         └──→ Subagent C (200k fresh) → executes Plan 3 → commits   │
│                                                                      │
│  Result: No context rot. Quality stays high across 10+ plans.       │
└──────────────────────────────────────────────────────────────────────┘
```

## Context Budget Guidelines

```
┌──────────────────────────────┬──────────────────────────────────────┐
│ Item                         │ Target budget                        │
├──────────────────────────────┼──────────────────────────────────────┤
│ System prompt                │ < 2,000 tokens                       │
│ Skills loaded (per session)  │ < 5,000 tokens total                 │
│ Working memory               │ < 20% of context window              │
│ Single SKILL.md file         │ < 500 lines (~3,000 tokens)          │
│ Subagent task prompt         │ < 1,000 tokens                       │
└──────────────────────────────┴──────────────────────────────────────┘
```

## Session Compaction Signs (time to compact or hand off)

- Agent starts repeating itself or forgetting recent instructions
- Response quality degrades noticeably mid-session
- Agent references stale information from much earlier in session
- Context shows > 70% utilisation

## Common Mistakes

- Loading all skills at session start — kills context budget immediately
- Putting large lookup tables in SKILL.md body — move to references/
- Not assigning skills explicitly to subagents (they don't inherit)
- Fighting context rot by repeating instructions — spawn fresh subagent instead