restructure-docs

name

restructure-docs

description

Analyze project documentation and restructure it for better separation of concerns and AI agent efficiency. Splits mixed-concern docs, merges undersized ones, moves orphaned sections, and removes harmful duplication. Triggers on "restructure docs", "reorganize docs", "split docs", "merge docs", "fix doc structure". Do NOT use for writing new documentation (use /explore-project) or initial setup (use /bootstrap-docs).

Restructure Docs

Analyze existing documentation and restructure it for better separation of concerns, discoverability, and AI agent efficiency. Moves content between files — does NOT rewrite content.

Principle: Move sections, don't change them. If content needs updating, that's /explore-project's job.

UX Note: Use AskUserQuestion to present the restructuring plan before making any changes.

Phase 1: Pre-flight

Check that docs/ exists and has content. List all .md files in docs/ including subdirectories.

If no docs found: Tell the user:

No documentation found. Run /bootstrap-docs first.

Stop.

If only 1-2 doc files exist: Tell the user:

Not enough documentation to restructure (only N files). Run /explore-project a few more times to build up content first.

Stop.

Phase 2: Analyze Current Structure

Read every .md file in docs/ (excluding exploration-manifest.md). Do NOT read or modify CLAUDE.md or AGENTS.md — those are managed separately. For each file, build a section map:

• File path
• Each top-level and second-level heading
• What code area or topic each section covers
• Approximate line count per section
• Total file line count

Phase 3: Identify Problems

Exclude docs/exploration-manifest.md from restructuring — it is auto-generated by /explore-project. Only update its references after restructuring other files.

Check for these issues in priority order:

Mixed concerns

A single doc covering unrelated topics. To detect: list the distinct code areas or topics each section covers. If a file has sections that serve different agent tasks (e.g., an agent doing architecture work wouldn't need the CSS section), it has mixed concerns. Larger files with mixed concerns are higher priority to split — but a large file with one focused topic (like a complete feature cookbook) is fine and should NOT be split just for size.

Duplication

The same concept explained in multiple files. To detect: compare section headings and content across files. Look for overlapping topics — same API, same pattern, same module described in two places.

Important: Duplication is acceptable when the docs are read during separate use cases and the duplicated section is important in both contexts. For example, if feature-patterns.md (read when building features) and architecture.md (read when refactoring core) both describe the entity store pattern, that duplication serves discoverability — an agent loading only one doc still gets the information it needs. Only flag duplication that doesn't serve partial-context reads.

When removing actual duplication: keep the more complete version, remove the other, and add a brief cross-reference (e.g., "See X.md for details on Y").

Orphaned sections

Content that doesn't belong in its current file. To detect: check if a section's topic matches the file's stated purpose (from its title or docs/README.md entry). A CSS patterns section inside an architecture doc is orphaned.

Poor discoverability

Important information buried deep where an AI agent wouldn't think to look. To detect: check if a section's heading clearly describes its content, and if the file it's in is where an agent would look for that topic.

Undersized files

Docs too small to justify their own file. Threshold: files under ~30 lines that could be merged into a related doc.

If no problems found: Tell the user:

Documentation structure looks clean. No restructuring needed.

Stop.

Phase 4: Design the Plan

For each problem found, propose a specific action:

• Split: Which file, along which section boundaries, into what new files
• Merge: Which files, into what combined file, under what heading structure
• Move: Which section, from where, to where
• Rename: Which file, to what (if the current name doesn't match the content)

Build a before/after comparison of docs/README.md showing how the index changes.

Present the plan:

AskUserQuestion: Here's my restructuring plan:

Problems found: N

[For each action, one line:]

• Split docs/architecture.md (350 lines) into docs/architecture.md + docs/infrastructure.md
• Move "CSS Patterns" section from docs/architecture.md to docs/feature-patterns.md
• Merge docs/small-note.md (20 lines) into docs/contributing.md

Before:

docs/README.md index:
- architecture.md — Architecture, infrastructure, CSS patterns
- small-note.md — Brief note about X

After:

docs/README.md index:
- architecture.md — High-level architecture, build system
- infrastructure.md — Infrastructure internals
- feature-patterns.md — Feature patterns, CSS patterns
- contributing.md — Contributing guidelines, X note

• Approve — execute the plan
• Modify — tell me what to change
• Cancel — do nothing

If user says Modify: Adjust the plan based on feedback and present again.

Phase 5: Execute

For each action in the approved plan, in this order:

1. Splits first — create new files, move sections out of the source file
2. Moves second — relocate sections between files
3. Merges third — combine files, delete the absorbed file
4. Renames last — rename files

For each move/split/merge:

• Cut the exact section content (heading + body) from the source
• Paste it in the target file at a logical position (group with related sections)
• Preserve the heading level — adjust if needed to fit the target file's structure (e.g., ## in one file might become ### as a subsection in another)
• Do NOT edit the section content itself — only move it

Prefer flat docs/ structure. Do not create subdirectories unless the user explicitly requests it.

After all moves are complete:

• Update docs/README.md to reflect the new file structure and descriptions
• Update docs/exploration-manifest.md if it exists — adjust the "Doc File" column in the coverage table to point to the new locations
• Search all doc files, CLAUDE.md, and AGENTS.md for cross-references (links like docs/old-name.md or references like "see architecture.md") and update them to point to the new locations

Phase 6: Verify

After executing, verify:

• Every section from the original docs exists in exactly one place in the new structure (except intentional duplicates kept for partial-context reads)
• No content was unintentionally lost — total line count may decrease if duplication was removed, but non-duplicated content should all be accounted for
• docs/README.md index matches the actual files in docs/
• No broken cross-references remain

If verification fails: Report what's wrong and fix it.

Phase 7: Report

Tell the user:

Restructuring complete.

• Files created: [list]
• Files modified: [list]
• Files deleted: [list]
• Sections moved: N

Troubleshooting

Can't determine where a section belongs

If a section covers a cross-cutting concern (e.g., "error handling" applies to multiple modules), keep it in the most general doc (usually architecture or contributing). Note it as a potential split candidate for the future.

Circular dependencies between docs

If splitting creates docs that heavily reference each other, the split boundary is wrong. Try a different split point or keep the content together.

docs/README.md doesn't exist

Create it as part of the restructuring. Use the same format as /bootstrap-docs would create.

Large doc that looks like it should be split

A large file (300+ lines) is only a problem if it has mixed concerns. A 500-line cookbook for one topic (e.g., feature patterns) is fine — splitting it forces agents to load multiple files for one task, hurting discoverability. Only split when sections serve different agent tasks.