doc-organizer

What this skill does

# Doc Organizer

Reorganize scattered documentation into a clear, maintainable structure with a single source of truth for every topic.

## Workflow

1. **Audit** -- Inventory all docs and classify their topics.
2. **Plan** -- Propose restructuring (moves, merges, deletions). Present the plan for confirmation.
3. **Execute** -- Apply the changes.
4. **Verify** -- Cross-check links, terminology, and completeness.

## 1) Documentation Audit

Scan the repository for documentation files:

- `**/*.md`, `**/*.rst`, `**/*.txt` in root, `docs/`, `guides/`, `references/`
- Inline doc comments in config files (YAML, TOML, JSON)

For each file, record:
- Primary topic and subtopics covered
- Last meaningful update (git log)
- Overlap with other files (flag duplicates)
- References to code that may have changed (staleness candidates)

Output: a summary table of all docs with topic, location, staleness risk, and duplicate flag.

## 2) Structure Optimization

Canonical locations:

| Content type | Location |
|---|---|
| Project overview, quickstart | `README.md` |
| How-to guides, tutorials | `guides/` |
| Architecture, deep-dives | `docs/` |
| API/CLI reference specs | `references/` or `docs/reference/` |
| Per-feature notes | colocated with feature code |

Propose a move plan as a table: `current path -> target path -> action (move/merge/delete/keep)`. Present the plan and wait for user confirmation before executing.

## 3) Deduplication

- Identify content repeated across multiple files.
- Choose one canonical location; replace duplicates with a short summary and a link.
- Prefer the more detailed version as the canonical source.

## 4) Terminology Normalization

- Extract key terms from docs (project name variants, feature names, abbreviations).
- Flag inconsistencies (e.g., "config" vs "configuration", "setup" vs "set up").
- Apply the project's preferred terminology uniformly.

## 5) Navigation Improvement

- Add or update a table of contents in long documents (>100 lines).
- Add cross-links between related docs.
- Ensure `README.md` links to all top-level guide and reference docs.
- Create an index page (`docs/README.md` or `docs/index.md`) if multiple docs exist without one.

## 6) Staleness Detection

Compare documentation claims against the current implementation:

- CLI flags/options mentioned in docs vs actual `--help` output or arg parser code.
- Config keys documented vs keys in schema/defaults.
- API endpoints documented vs route definitions.

Flag mismatches as "needs update" with the specific discrepancy.

## Verification Checklist

- [ ] No broken internal links (relative paths resolve correctly)
- [ ] No orphaned docs (every doc reachable from README or index)
- [ ] Terminology consistent across all files
- [ ] Examples match current CLI/API behavior
- [ ] Duplicate content eliminated (single source of truth per topic)