What Progressive Disclosure Means
Progressive Disclosure is a strategy for loading context into AI agents efficiently. Instead of dumping an entire codebase's context into a prompt, the agent starts with a high-level overview and progressively loads more detail only for the areas relevant to the current task.
The term comes from UX design, where it means showing users basic information first and revealing complexity on demand. Applied to AI context, the principle is the same: give the agent the right context at the right depth at the right time.
Why It Matters
AI models have finite context windows. Even with modern models supporting 100K+ tokens, large codebases easily exceed those limits. And more context isn't always better — irrelevant context can actually hurt performance by diluting the signal.
Progressive Disclosure solves both problems:
- Token efficiency — Load only what's needed. Measured at 37% token reduction in real deployments.
- Signal quality — The context that is loaded is relevant and focused.
- Scalability — Works on codebases of any size, because you're never loading everything at once.
How It Works
In the Intent Layer, Progressive Disclosure follows the hierarchy of Intent Nodes:
-
Level 0 — Root context. The agent reads the root Intent Node: system overview, major modules, key patterns. This gives it a mental model of the entire system.
-
Level 1 — Module context. Based on the task, the agent identifies which modules are relevant and loads their Intent Nodes. Now it understands the specific area it's working in.
-
Level 2 — Component context. For the specific files and functions the task touches, the agent loads detailed context: implementation patterns, edge cases, related tests.
At each level, the agent knows what exists at deeper levels (via downlinks in the Intent Nodes) but only loads what the task requires.
Example
Consider an agent tasked with "add retry logic to the payment webhook handler":
- Level 0: Reads root node — learns the system has a payment service, auth service, notification service. Payment service is relevant.
- Level 1: Reads payment service node — learns webhooks live in
webhooks/, retries should use exponential backoff, all changes need audit log entries. - Level 2: Reads the specific webhook handler files and related test patterns.
Without Progressive Disclosure, the agent would either (a) try to read the entire codebase (token explosion) or (b) jump straight to the webhook file with no system understanding (missing the audit log requirement, the retry convention, etc.).
Progressive Disclosure vs. RAG
RAG retrieves context reactively — the agent asks a question, and the system finds relevant chunks. Progressive Disclosure loads context proactively and hierarchically — the agent navigates a structured map.
The approaches aren't mutually exclusive, but Progressive Disclosure tends to produce better results for code tasks because it preserves the relationships between pieces of context, not just individual chunks.