Part of Mechanisms of Vibe Coding

Mechanism: Progressive Disclosure

One-sentence definition

Progressive disclosure is starting an agent session with minimal context — goal, anchors, failing output — and adding files or docs only when the agent is stuck or working on the wrong layer.

The problem

You @ every file that might matter before the agent reads one line. Context fills with noise. The model confidently edits the wrong module because a unrelated doc mentioned a similar keyword. You saved time on “being thorough” and lost time on misdirection.

Pre-loading everything feels safe. It is often anti-information — attention spread too thin to see the actual bug.

Symptoms:

• Agent cites files you attached but did not need
• Correct fix exists in a file never loaded
• Long context but wrong diagnosis
• Slow responses with no better outcomes

How it works

Start with a minimal disclosure set:

1. Goal + constraints
2. Anchor files (1–2 max)
3. Files directly implicated by the error or goal
4. Failing verify output (trimmed)

  Minimal context
       │
       ▼
  Agent pass
       │
       ├── success ──► stop adding context
       │
       └── stuck / wrong layer
              │
              ▼
  Add ONE disclosure item (file, doc, diagram)
              │
              ▼
  Next pass (do not re-attach everything)

Each disclosure step should answer: “What did the agent lack?” — not “what might theoretically help.”

Pairs with context budget: budget is the limit; progressive disclosure is the fill strategy.

When to use it

• Large repos and unfamiliar code
• After scope fence narrowed the job
• When @codebase tempted you but the task is localized
• Long chats where early tangents polluted context — prefer new chat + minimal set

When not to use it

• Single-file script — disclosure ladder adds ceremony
• Agent must see full graph (rare) — disclose the graph once, with reason
• Using disclosure to avoid writing a clear goal — fix the goal first

Failure modes

Hoarding at start — Full tree attached preemptively. Fix: List minimal set; justify each @ in one line.

Disclosure flood — Five files added on one stuck pass. Fix: One file per stuck pass.

Wrong disclosure — Added UI files for a bootstrap timing bug. Fix: Use error stack and goal to pick the next file.

Never disclosing — Agent loops on missing context you could add. Fix: After two identical failures, add the obvious missing module.

Re-disclosing history — Re-pasting entire prior chats. Fix: Session handoff summary, not transcript.

Minimal example

Context: Verbose health fails — uptime always 0.

Disclosure ladder:

1. Start: @health.ts @health.test.ts + test failure + goal block.
2. Pass 1 fails: Agent edits handler only → still 0.
3. Disclose +1: @bootstrap.ts only (“uptime sourced from bootstrap”).
4. Pass 2: Fix lands. Do not add @server.ts or README.

Done when: Fix required at most one disclosure step beyond the minimal set.

Tool instances (optional deep-dive)

Portable idea above; this section is tool-specific. Date: June 2026.

Cursor

• Avoid @codebase until disclosure ladder exhausted.
• Agent ask: “Before attaching more files, state what you need and why.”
• New chat with minimal set beats bloated old chat.
• Rules: standing anchors auto-included; everything else on request.

Other tools

RAG with low top-k, Aider file add one-by-one — same discipline.

Related mechanisms

• Context budget — how much context you allow
• Anchor files — what to include at step zero
• Scope fence — disclosure stays inside the fence

Try it yourself

Exercise: Plan a session with max 3 files at start. Write the disclosure ladder: “If stuck, add ___ because ___. “

You need: One bug; three minutes

Done when: Third disclosure slot is named before you open the agent.