Progressive Disclosure:restructure

Restructure Progressive Disclosure

Refactor the repository's highest-precedence root configuration file to contain a thematic, book-style index of all documentation. Organizes references like a table of contents — grouped by theme, ordered for progressive discovery.

Principles

• Preserve existing content: The root configuration file's existing rules and instructions are kept intact. The index is inserted as a clearly delimited section.
• Idempotent: Re-running produces the same result. HTML comment markers delineate the generated section so subsequent runs replace rather than duplicate.
• Thematic ordering: Documents are grouped by theme following the taxonomy in references/themes.md, not by directory structure. The ordering mimics a book's table of contents.
• Conversational links: Each reference uses a natural-language description that tells the agent when to load the document, not just what it contains. Example: "For TypeScript conventions, see docs/typescript.md" rather than a bare link.

Workflow

Step 0: Resolve Target File

Check whether the user explicitly named a target file in their prompt (e.g. "restructure docs/CONTRIBUTING.md", "update README.md").

• If a file was named: use it as the target. Verify it exists before proceeding; if it does not, halt and report the missing path.
• If no file was named: fall through to Step 1.

Step 1: Select Target Root Configuration File

Skip this step if Step 0 resolved a target.

Apply precedence rules to find the highest-precedence existing root configuration file:

1. AGENTS.md
2. CLAUDE.md
3. GEMINI.md
4. USER.md
5. TOOLS.md
6. BOOTSTRAP.md
7. DESIGN.md
8. NOTICE.md

If none exist, create AGENTS.md as the target.

Read the target file to understand its existing structure.

Step 2: Discover All Documentation

Run the discovery script to enumerate all .md files:

"${CLAUDE_PLUGIN_ROOT}/skills/analyze/scripts/discover.sh" "$(pwd)"

Exclude root configuration files themselves from the index (they are the container, not indexed content). Include README.md as an indexed document.

Index only visible files. Inside a git repository the discovery script already restricts the documentation pool to git-tracked files — never add an untracked or gitignored file to the index, since other agents cannot load it. If the existing file already links to such a file, drop that link and note it.

When the script reports a SAME-CONTENT: symlink group (e.g. CLAUDE.md symlinked to AGENTS.md), index the underlying file once — do not list both the symlink and its target as separate entries.

Step 3: Classify Documents by Theme

For each discovered document, classify it into a theme using the taxonomy in references/themes.md. Apply signals in order:

1. Path-based — match directory components against the path signal table
2. Filename-based — match against the filename signal table
3. Heading-based — read the first H1 or H2 and match keywords
4. Fallback — place in Appendix

This classification is semantic — use judgment for ambiguous documents. A file at docs/auth-flow.md with H1 "Authentication Architecture" belongs in Architecture, not Security.

Step 4: Generate the Index

Build the index section with this structure:

<!-- progressive-disclosure:index:start -->
## Documentation Index

### Getting Started
- For initial setup and installation, see [`docs/quickstart.md`](docs/quickstart.md)

### Architecture
- For system design and component relationships, see [`docs/architecture.md`](docs/architecture.md)
- For data flow diagrams, see [`docs/data-flow.md`](docs/data-flow.md)

### Development
- For TypeScript conventions, see [`docs/typescript.md`](docs/typescript.md)

[...additional themes with documents...]
<!-- progressive-disclosure:index:end -->

Rules for the generated index:

• Only include themes that have at least one document
• Each entry is a single line with a conversational prefix and a markdown link
• The conversational prefix describes when the agent should load that document
• Within each theme, order per references/themes.md within-theme rules
• Skip themes with zero documents

Step 5: Insert or Replace in Target File

If markers already exist (<!-- progressive-disclosure:index:start --> and <!-- progressive-disclosure:index:end -->): Replace everything between the markers (inclusive) with the new index block.

If no markers exist: Check for an existing section heading like ## Documentation, ## Index, ## Table of Contents, or ## References. If found, insert the index block immediately after that heading (replacing its body up to the next ##). If no matching section exists, append the index block at the end of the file.

Step 6: Verify

After writing the index:

1. Confirm all linked files actually exist and are git-tracked (no broken or phantom references)
2. Confirm the marker pair is present exactly once
3. Count documents indexed vs total documents found — report coverage percentage
4. If coverage is below 100%, list unindexed documents and their paths

Presentation

After restructuring, display:

• Which root configuration file was modified
• How many documents were indexed across how many themes
• Coverage percentage
• Any documents that were skipped and why
• A reminder that re-running is safe (idempotent via markers)