| name | progressive-disclosure:analyze |
| description | This skill should be used when the user asks to "analyze documentation structure", "audit progressive disclosure", "map documentation references", "find orphaned docs", "check context rot risk", "audit CLAUDE.md", "audit AGENTS.md", or wants to understand how a repository's documentation is structured for AI agent consumption. Produces a disclosure map, orphan report, and anti-pattern findings. |
| disable-model-invocation | false |
Analyze Progressive Disclosure
Audit how a repository progressively discloses its documentation through root configuration files. Produce a structured report covering the disclosure hierarchy, reference graph, orphaned documents, anti-patterns, and actionable recommendations.
Concepts
Progressive disclosure for AI agents operates on three layers:
- Layer 1 — Discovery: Lightweight metadata always loaded at session start (root configuration file names, one-line descriptions, file indexes). Consumes minimal instruction budget.
- Layer 2 — Activation: Specific instructional files fetched on-demand when the agent identifies a relevant task phase. Loaded via conversational links from root configuration files.
- Layer 3 — Deep Dive: Dense reference material, source code, API docs. Loaded only when the agent must execute against detailed content.
Root configuration files are the Layer 1 entry points. Their quality determines whether the rest of the repository is discoverable.
Git Visibility
When the target is inside a git repository, only git-tracked files are part of the repository. Untracked files and gitignored files are treated as invisible — they do not appear in the documentation pool, the orphan report, or the metrics, because an agent cloning the repo will never see them. Git never ignores an already-tracked file, so a single "is it tracked?" test enforces both conditions (tracked and not ignored).
The one exception is root configuration entry points themselves (AGENTS.md, CLAUDE.md, GEMINI.md, …): these are detected by existence, since they are often audited before being committed. In its indexed-documentation role, README.md follows the visibility rule like any other doc.
If a root configuration file references an invisible file, that is a phantom reference — the link points at content no one else can load. Flag it and recommend either removing the reference or adding the file to git.
When the target is not a git repository, every matching file is included (filesystem walk with standard excludes).
Symbolic Links
Two paths can be the same underlying file via a symbolic link — most commonly CLAUDE.md symlinked to AGENTS.md. The discovery script reports these as SYMLINK: lines and SAME-CONTENT: groups. Files in a SAME-CONTENT group are one file under several names; never report them as duplicate content.
Default File List
When no target is explicitly specified, scan for the following files (in order):
README.md — human-facing documentation about the project; treat as indexed content, not a configuration entry pointAGENTS.mdCLAUDE.mdGEMINI.mdUSER.mdTOOLS.mdBOOTSTRAP.mdDESIGN.mdNOTICE.md
Workflow
Step 0: Resolve Target File
Check whether the user explicitly named a target file in their prompt (e.g. "analyze docs/CONTRIBUTING.md", "audit README.md").
- If a file was named: scope the analysis to that file only. Skip root configuration file precedence resolution — treat the named file as the subject of Steps 2–5.
- If no file was named: analyze all root configuration files found by the discovery script as normal.
Step 1: Run Discovery Script
Execute the discovery script to gather raw data:
"${CLAUDE_PLUGIN_ROOT}/skills/analyze/scripts/discover.sh" "$(pwd)"
The CLAUDE_PLUGIN_ROOT variable resolves to the plugin's installed location. The script produces these sections:
- Git tracking — whether the target is inside a git work tree (determines visibility, above)
- Root configuration files — entry points found
- Documentation files — visible
.md files (tracked-only inside a git repo)
- Symlinks —
SYMLINK: lines and SAME-CONTENT: groups (do not treat grouped files as duplicates)
- Untracked references —
UNTRACKED-REF: phantom references from config files to invisible files
- Reference graph — each reference marked
[EXISTS], [UNTRACKED], or [MISSING]
- Orphan detection — visible docs not reachable from any config file
- Metrics — counts and budget figures
Step 2: Classify Disclosure Layers
For each root configuration file found, classify its contents against the three-layer model:
- Layer 1 content (belongs in root configuration file): project description, build commands, file indexes, conversational links to specialized docs
- Layer 2 content (should be linked, not inlined): coding conventions, architecture decisions, testing strategies, workflow instructions
- Layer 3 content (should never be in a root configuration file): full API references, schema dumps, extensive code examples, raw data
Flag any Layer 2 or Layer 3 content found inlined in root configuration files.
Step 3: Detect Anti-Patterns
Check for these documented failure modes:
| Anti-Pattern | Detection | Severity |
|---|
| Monolithic root configuration file | CLAUDE.md >300 lines or AGENTS.md >1500 words | High |
| Missing index | Root configuration file has no links to other docs | High |
| Generic instructions | Phrases like "write clean code", "follow best practices", "think step by step" | Medium |
| Style rules in root configuration file | Formatting/linting rules that belong in tool config (eslint, prettier) | Medium |
| Orphaned documentation | .md files not referenced from any root configuration file | Medium |
| Broken references | Links in root configuration files pointing to non-existent files ([MISSING]) | Critical |
| Phantom references | Links to files that exist on disk but are untracked or gitignored (UNTRACKED-REF: / [UNTRACKED]) | Critical |
| Duplicate content | Same instructions in multiple root configuration files — but first exclude SAME-CONTENT: symlink groups, which are one file, not duplicates | Medium |
| No root configuration files at all | Repository has zero root configuration files | Critical |
Step 4: Estimate Instruction Budget Impact
Provide a rough assessment:
- Count distinct imperative instructions in each root configuration file (lines starting with verbs, bullet points with directives, numbered steps)
- Recall: agents reliably follow ~150-200 instructions total; baseline system prompt consumes ~50
- Flag if root configuration file instructions exceed ~100 (leaves insufficient budget for task-specific context)
Step 5: Produce Report
Present findings inline (never hide behind a file path). Structure the report as:
1. Disclosure Map
Visual tree showing root configuration files → referenced docs → their sub-references. Mark each node with its disclosure layer (L1/L2/L3).
2. Root Configuration File Health
Per-file assessment: word count, line count, instruction estimate, layer violations found.
3. Reference Graph
What links to what. Highlight broken links ([MISSING]), phantom links to untracked/gitignored files ([UNTRACKED]), and circular references. For each phantom reference, recommend removing the reference or adding the target to git.
4. Orphan Report
Documentation files not reachable from any root configuration file. Group by directory.
5. Anti-Pattern Findings
Each finding with severity, location, and specific remediation.
6. Recommendations
Prioritized list of changes to improve progressive disclosure. Lead with highest-impact, lowest-effort items. When restructuring would help, suggest running progressive-disclosure:restructure.
Presentation Rules
- Show all findings inline — never say "see the report file"
- Use tables for structured data, trees for hierarchies
- Lead with the most critical findings
- Quantify: "CLAUDE.md has 847 words across 312 lines — 2.8x the recommended maximum"
- End with a clear next-step recommendation
