docs: restructure documentation following Diataxis framework

.github/skills/diataxis-docs-planner/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: diataxis-docs-planner
+description: Audit, plan, and structure Python package documentation following the Diátaxis framework (tutorials, how-to guides, reference, explanation). Use when asked to plan documentation, audit existing docs, identify documentation gaps, restructure docs, create a documentation roadmap, or organize documentation for a Python package. Triggers on "plan docs", "audit documentation", "structure docs", "documentation roadmap", "what docs do I need", "organize documentation".
+---
+
+# Diátaxis Documentation Planner
+
+Audit existing documentation and produce a structured plan following the Diátaxis framework - four quadrants of documentation that serve distinct user needs.
+
+## The Four Quadrants
+
+| Quadrant | Orientation | User mode | Serves | Question answered |
+|----------|-------------|-----------|--------|-------------------|
+| **Tutorial** | Learning | Study | Acquisition of skill | "Can you teach me to…?" |
+| **How-to guide** | Task | Work | Application of skill | "How do I…?" |
+| **Reference** | Information | Work | Application of skill | "What is…?" |
+| **Explanation** | Understanding | Study | Acquisition of skill | "Why…?" |
+
+## Compass Decision Tree
+
+Classify any content by asking two questions:
+
+1. **Action or cognition?** Does it guide what the user *does*, or inform what the user *knows*?
+2. **Acquisition or application?** Does it serve *study* (learning) or *work* (applying skills)?
+
+| Informs… | Serves… | → Quadrant |
+|----------|---------|------------|
+| Action | Acquisition (study) | Tutorial |
+| Action | Application (work) | How-to guide |
+| Cognition | Application (work) | Reference |
+| Cognition | Acquisition (study) | Explanation |
+
+## Audit Workflow
+
+### Step 1: Analyze the Codebase
+
+Examine the package to understand what needs documenting:
+
+- Read `pyproject.toml` for package name, description, dependencies, entry points, CLI tools
+- Scan `src/<package>/` for public modules, classes, functions (the API surface)
+- Check for CLI entry points, configuration files, plugin systems
+- Look at `tests/` for usage patterns and features exercised
+- Check `examples/` if present
+
+### Step 2: Inventory Existing Documentation
+
+Read all files in `docs/` and classify each page by quadrant using the compass:
+
+- For each page, note: file path, current title, actual quadrant, intended quadrant
+- Flag pages that mix quadrants (e.g., a "getting started" that is half tutorial, half reference)
+- Flag pages that are misclassified (e.g., an "explanation" page that is really a how-to)
+
+### Step 3: Identify Gaps
+
+For a well-documented Python package, expect at minimum:
+
+**Tutorials** (at least 1):
+- Getting Started / First Steps - install, import, first meaningful result
+
+**How-to Guides** (varies by feature count):
+- One per common task/problem users face
+- Installation/setup variations (different platforms, configs)
+- Integration with other tools/libraries
+- Configuration for common scenarios
+- Troubleshooting guide
+
+**Reference** (comprehensive):
+- API reference (all public modules, classes, functions)
+- CLI reference (if applicable)
+- Configuration reference (all settings/options)
+- Error codes / exceptions (if applicable)
+
+**Explanation** (at least 1-2):
+- Architecture / design overview
+- Key concepts and terminology
+- Advantages of the chosen tooling and patterns (focus on benefits, not justification)
+
+### Step 4: Produce the Plan
+
+Output a structured documentation plan:
+
+1. **Gap analysis table** - what exists, what is missing, what needs reclassification
+2. **Recommended pages** - organized by quadrant, with title, purpose, priority (high/medium/low)
+3. **MkDocs nav structure** - ready to paste into `mkdocs.yml`
+4. **Implementation order** - tutorials and key how-tos first (highest user impact)
+5. **Skill recommendations** - name the specific writer skill for each page:
+   - Tutorial pages → `diataxis-tutorial-writer`
+   - How-to pages → `diataxis-howto-writer`
+   - Reference pages → `diataxis-reference-writer`
+   - Explanation pages → `diataxis-explanation-writer`
+
+## MkDocs Nav Patterns
+
+Typical Python package nav structure:
+
+```yaml
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md          # tutorial
+  - How-to Guides:                                # how-to
+    - how-to/index.md
+    - How to Configure X: how-to/configure-x.md
+    - How to Integrate with Y: how-to/integrate-y.md
+  - Reference:                                    # reference
+    - reference/index.md
+    - API Reference: reference/api.md
+    - CLI Reference: reference/cli.md
+    - Configuration: reference/configuration.md
+  - Explanation:                                  # explanation
+    - explanation/index.md
+    - Architecture: explanation/architecture.md
+  - Contributing: contributing.md                 # how-to (for contributors)
+```
+
+For complex packages with multiple user types or deployment targets, see [references/compass-and-patterns.md](references/compass-and-patterns.md) for multi-layer hierarchy and two-dimensional structure guidance.
+
+## Common Anti-Patterns to Flag
+
+- **The mega-README**: Everything in one file - split by quadrant
+- **Tutorial-reference hybrid**: "Getting Started" that is actually an API walkthrough - separate
+- **How-to disguised as explanation**: "Understanding X" that is really step-by-step instructions
+- **Missing tutorials entirely**: Only reference docs (common with auto-generated docs)
+- **Explanation scattered everywhere**: Bits of "why" sprinkled across how-to guides - consolidate
+
+## Quality Signals
+
+When auditing, also note:
+
+- **Functional quality**: accuracy, completeness, consistency, precision
+- **Deep quality**: flow, fit to user needs, anticipation of the user
+- Use the `mkdocs` skill for site configuration and build concerns - this skill focuses on content structure
+
+## Output Format
+
+```markdown
+## Documentation Audit: <package-name>
+
+### Current State
+
+| Page | File | Current Quadrant | Issues |
+|------|------|-----------------|--------|
+| ... | ... | ... | ... |
+
+### Gap Analysis
+
+| Quadrant | Existing | Missing | Priority |
+|----------|----------|---------|----------|
+| Tutorial | ... | ... | ... |
+| How-to | ... | ... | ... |
+| Reference | ... | ... | ... |
+| Explanation | ... | ... | ... |
+
+### Recommended Pages
+#### Tutorials (use `diataxis-tutorial-writer`)
+1. **Getting Started** - Install, first use, verify result [HIGH]
+
+#### How-to Guides (use `diataxis-howto-writer`)
+1. **How to configure X** - ... [HIGH]
+
+#### Reference (use `diataxis-reference-writer`)
+1. **API Reference** - Full public API [HIGH]
+
+#### Explanation (use `diataxis-explanation-writer`)
+1. **Architecture Overview** - ... [MEDIUM]
+
+### Proposed MkDocs Nav
+nav:
+  ...
+```

.github/skills/diataxis-docs-planner/references/compass-and-patterns.md

@@ -0,0 +1,119 @@
+# Diátaxis Compass and Documentation Patterns
+
+## Full Compass Table
+
+| Content characteristic | Tutorial | How-to Guide | Reference | Explanation |
+|----------------------|----------|-------------|-----------|-------------|
+| **What they do** | Introduce, educate, lead | Guide | State, describe, inform | Explain, clarify, discuss |
+| **Answers the question** | "Can you teach me to…?" | "How do I…?" | "What is…?" | "Why…?" |
+| **Oriented to** | Learning | Goals | Information | Understanding |
+| **Purpose** | Provide a learning experience | Help achieve a particular goal | Describe the machinery | Illuminate a topic |
+| **Form** | A lesson | A series of steps | Dry description | Discursive explanation |
+| **Analogy** | Teaching a child to cook | A recipe in a cookbook | Info on a food packet | Article on culinary history |
+
+## Boundary Blur Risks
+
+Adjacent quadrants share affinities that cause content to bleed across boundaries:
+
+| Shared trait | Quadrants at risk | Common mistake |
+|-------------|------------------|----------------|
+| Guide action | Tutorial ↔ How-to | Conflating "getting started" with "how to configure" |
+| Serve application of skill | Reference ↔ How-to | Stuffing procedures into API docs |
+| Contain propositional knowledge | Reference ↔ Explanation | Expanding reference examples into explanations |
+| Serve acquisition of skill | Tutorial ↔ Explanation | Overloading tutorials with background context |
+
+## Python Package Page Patterns
+
+### Typical Tutorial Pages
+- **Getting Started** - Install via pip/uv, import, call a function, verify output
+- **Your First <Feature>** - Build something small end-to-end
+- **Tutorial Series Part N** - Multi-part progressive learning path
+
+### Typical How-to Pages
+- **How to install** (with variations: pip, uv, conda, Docker, from source)
+- **How to configure <feature>** - Settings, env vars, config files
+- **How to integrate with <library>** - Using the package alongside another tool
+- **How to deploy** - Production setup, CI/CD integration
+- **How to extend / write plugins** - For extensible packages
+- **How to migrate from vX to vY** - Upgrade guides
+- **Troubleshooting** - Common problems and solutions
+
+### Typical Reference Pages
+- **API Reference** - Auto-generated via mkdocstrings (modules → classes → methods)
+- **CLI Reference** - Commands, flags, options, exit codes
+- **Configuration Reference** - All settings with types, defaults, descriptions
+- **Error Reference** - Exception classes, error codes, meanings
+- **Changelog** - Version history (auto-generated via git-cliff or similar)
+
+### Typical Explanation Pages
+- **Architecture Overview** - How the package is structured and why
+- **Design Decisions** - Why certain approaches were chosen
+- **Key Concepts** - Domain terminology and mental models
+- **Comparison with Alternatives** - How this package differs from similar tools
+- **Performance Characteristics** - Complexity, benchmarks, trade-offs
+- **Security Model** - Trust boundaries, threat model (when applicable)
+
+## Complex Hierarchy Patterns
+
+### Single Product, Multiple User Types
+
+```text
+docs/
+  getting-started.md                    # tutorial (all users)
+  how-to/
+    users/                              # how-to for end users
+      configure.md
+      troubleshoot.md
+    developers/                         # how-to for integrators
+      extend.md
+      write-plugins.md
+    contributors/                       # how-to for maintainers
+      development-setup.md
+      release-process.md
+  reference/
+    api.md                              # reference (shared)
+    cli.md
+    config.md
+  explanation/
+    architecture.md                     # explanation (shared)
+    design-decisions.md
+```
+
+### Single Product, Multiple Deployment Targets
+
+```text
+docs/
+  getting-started.md                    # tutorial (generic)
+  how-to/
+    install-pip.md                      # how-to per target
+    install-docker.md
+    install-from-source.md
+    deploy-aws.md
+    deploy-gcp.md
+  reference/                            # reference (shared)
+    api.md
+    config.md
+  explanation/                          # explanation (shared)
+    architecture.md
+```
+
+## Contents Page Guidelines
+
+- Landing pages should read as overviews, not bare lists
+- Keep lists under 7 items per group; break into sub-sections if longer
+- Use headings with brief introductory text to provide context
+- Each landing page should help the user quickly find what they need
+
+## Quality Checklist
+
+### Functional Quality (measurable)
+- [ ] Accurate - code examples run, commands produce stated output
+- [ ] Complete - all public API surface documented
+- [ ] Consistent - terminology, formatting, style uniform across pages
+- [ ] Up-to-date - matches current version of the package
+
+### Deep Quality (experiential)
+- [ ] Flow - reader progresses naturally without jarring transitions
+- [ ] Fit to needs - each page serves a clear user need
+- [ ] Anticipation - docs address questions before they arise
+- [ ] Minimal friction - no unnecessary detours or digressions