docs-reorg

name

docs-reorg

description

Use this skill whenever the user wants to classify, audit, or restructure documentation pages in a repository. Triggers include: analyzing a doc page to determine its type, identifying mixed-purpose pages, planning how to split a page into how-to / reference / explanation / tutorial / way-finding pages, auditing a section of a repository for documentation quality, or any mention of Diataxis. Also use when the user points at a file and asks what type it is, what's wrong with it, or how it should be split. Use proactively when the user describes messy, migrated, or inherited documentation that needs reorganization.

Docs reorg

This skill classifies documentation pages against 5 types of documentation and produces a split plan for mixed pages. This is typically the first step in a documentation reorganization project, but it can also be used for auditing or classification without reorg. You need to know about Diataxis and its content types to use this skill effectively. Read the reference files in references/ before classifying.

The 5 types are based on the Diataxis framework, which defines four core types — tutorial, how-to, explanation, reference — plus a fifth type for way-finding/landing pages.

Before classifying, read both reference files:

• references/reasoning.md — the reasoning behind Diataxis; how to think about type boundaries
• references/page-types.md — the type definitions, diagnostic signals, and mix patterns

---

Input

Input is a file or folder path in this repository. If the folder structure is complex, that is, if there are sub-folders, then tell the user to start on a folder with no sub-folders and analyze those files first. Once those files are classified, then the user can move up to the parent folder and classify the content in it. Read the full file before proceeding. Do not skim — heading structure, verb mood, and register shifts are all diagnostic signals.

Workflow

Step 1 — Read

Read the full page. Note:

• The title and all headings
• Whether the verb mood shifts (imperative > declarative > lookup)
• Whether there is one clear job-to-be-done or several
• Whether there are steps, and if so, whether they teach or just instruct

Step 2 — Classify

Score the page against each type using the definitions in references/page-types.md.

Output a classification table:

Type	Confidence	Reasoning
Tutorial	low / medium / high	one-line reason
How-to	low / medium / high	one-line reason
Explanation	low / medium / high	one-line reason
Reference	low / medium / high	one-line reason
Way-finding/Landing	low / medium / high	one-line reason

Then state:

• Primary type — the highest-confidence match
• Mixed — yes or no (two or more types)

If confidence is low across all types, flag the page as unclassifiable. Do not force a classification.

If genuinely uncertain about a type boundary, note it and refer the user to https://diataxis.fr/compass/ or ask them to clarify.

Step 3 — Split plan (mixed pages only)

If the page is mixed, list the output pages:

SPLIT PLAN
----------
Source: <file path>
Verdict: Mixed — [Type A] + [Type B]

Output pages:
  1. <Suggested title>  >  <Type>
  2. <Suggested title>  >  <Type>

Content to cut entirely:
  - <item>  [reason]

Keep it lean — titles and types only. The user decides file names and where content goes during implementation.

Step 4 — Navigation shape for MkDocs (when reorganizing by Diataxis)

Use this step for reorg in MKDocs only.

When restructuring a section into Diataxis folders, follow this two-file pattern:

Top-level .NAV.md (minimal structure):

• Links only to the section's main index.md and Diataxis folder names.
• No detailed page links.
• Serves only to signal folder structure to the navigation system.

Section index.md (full table of contents and entry point):

• Acts as the landing page explaining the section.
• Includes ## Choose the right documentation type section grouping all pages by Diataxis type (Explanation, How-to, Reference, Tutorials).
• Lists individual pages under each type with full links.
• Optionally includes a ## Common starting points section for frequent use cases.
• Readers explore the full site from this page, not from .NAV.md.

Example of the two-file pattern:

.NAV.md:

# Topic name

- [Topic title ](index.md)
- [Explanation](explanation/)
- [How-to](how-to/)
- [Reference](reference/)
- [Tutorials](tutorials/)

index.md:

# Topic to reorg

Use this section to find the right kind of documentation for working with Topic.

## How to read this documentation 

```markdown
# [Section Name]

[1-2 paragraph overview of section]

## Where to Start

### New to [Topic]?
Start here to understand the concepts:
- [Explanation Page](explanation/overview.md) - Conceptual foundation

### Ready to [Action]?
Follow the step-by-step guide:
- [Tutorial Page](tutorial/getting-started.md) - First-time setup

### Need Specific Instructions?
Browse task-oriented how-to guides:
- [How-to 1](how-to/task1.md) - Specific task
- [How-to 2](how-to/task2.md) - Another task

### Looking for Technical Details?
Access reference materials:
- [Reference 1](reference/standards.md) - Technical specs
- [Reference 2](reference/catalog.md) - Available resources

## Need Help?
[Contact information, support channels]

Common starting points

• Need to know how to do something: How-to guides
• Need to understand something: Explanations
• Need to look up a fact: Reference materials
• Need to learn by doing: Tutorials

** Do not create `.NAV.md` inside Diataxis folders** (`how-to/`, `reference/`, `explanation/`, `tutorials/`) unless explicitly requested. Rely on MkDocs folder discovery for typed folders.

## Critical rules

- **One type per output page** — never propose a page that mixes types
- **Steps alone do not make a tutorial** — a tutorial has a learning goal and a stated outcome; steps without those markers are a how-to
- **Way-finding contains links, not content** — any instructional or conceptual content on a landing page is mix, not way-finding
- **Prefer shallow top-level nav in Diataxis sections** — top-level `.NAV.md` should route to Diataxis folders; detailed page links belong in the section landing page and typed folder `index.md` files
- **No folder-level `.NAV.md` files by default** — rely on MkDocs folder discovery for typed folders unless the user requests folder-level nav explicitly
- **Reference is for consulting, not reading** — if a user would read it linearly, it is not pure reference
- **Do not invent content** — the split plan only redistributes what exists on the page
- **Use sentence case for headings and titles**