Second Brain

progressive-disclosure-as-ambiguity-resolution-pattern

2 min read

Progressive-disclosure-as-ambiguity-resolution pattern

Progressive-disclosure-as-ambiguity-resolution

When a SKILL.md (or any large setup file) has duplicate section numbering (e.g., ## 1-10 series co-existing with ## Section 9-11 series — a Law 2 Zero Ambiguity violation), the correct resolution is not deletion but extraction:

  1. Move duplicate-numbered sections to docs/<topic>.md files within the skill’s directory
  2. Replace each extracted section in main SKILL.md with a pointer block (2-3 lines summarizing what’s in docs/ + the relative link)
  3. Renumber remaining sections sequentially in main

Concrete evidence (this session, 16-Apr-2026)

  • frontend-intelligence/SKILL.md: 761 lines → 406 lines (47% reduction)
  • 6 docs/ files created: product-type-routing.md (27), dial-commands.md (16), design-system-master.md (81), build-pipeline.md (57), design-reference-library.md (126), frontend-data-integration.md (79)
  • Total lines across main + 6 docs: 792 (vs 761 original, +31 for pointer blocks + docs frontmatter)
  • 100% unique content preserved, duplicate section numbering eliminated, lint unchanged at 71/71 PASS
  • fusion-invariants-lint.py still passes because skill name/frontmatter/14 invariants unchanged in main

When operator says “resolve ambiguities but don’t drop unique content”

Progressive disclosure extraction IS the technique. Not deletion. Not consolidation. Extract-and-pointer.

Companion rule

Size-alone finding (over soft target but under hard limit, no ambiguity) does NOT authorize refactor per operator directive "do not change these skills". Refactor is authorized ONLY when (a) ambiguity present AND (b) unique content preservation guaranteed via extraction.

Creating a new skill from pre-approved spec → setup-curator guard is ADVISORY (informational reminder). Modifying a pre-existing skill — including retrofits, progressive disclosure splits — is SUBSTANTIVE. Full setup-curator protocol MUST run: anti-bloat filters, routing decision tree, cascade-update verification. The tell: if the file exists and the change isn’t a typo/format fix, treat as substantive.

Complementary context: WebGPU exemplar

The WebGPU skill at github.com/dgreenheck/webgpu-claude-skill demonstrates the same progressive-disclosure architecture applied proactively (not reactively): overview → cheatsheet → deep docs → examples, loaded on-demand per complexity tier. The two cases — reactive (this entry, ambiguity-triggered refactor) and proactive (WebGPU, architecture-by-design) — use the same mechanism. A skill built proactively with progressive disclosure never develops the ambiguity that forces reactive refactor.

Graph View

Backlinks