docs(skills): add canonical Diataxis folder paths to all writer skills

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

@@ -5,7 +5,7 @@ description: Audit, plan, and structure Python package documentation following t
 
 # 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.
+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
 
@@ -55,7 +55,7 @@ Read all files in `docs/` and classify each page by quadrant using the compass:
 For a well-documented Python package, expect at minimum:
 
 **Tutorials** (at least 1):
-- Getting Started / First Steps - install, import, first meaningful result
+- Getting Started / First Steps — install, import, first meaningful result
 
 **How-to Guides** (varies by feature count):
 - One per common task/problem users face
@@ -73,62 +73,62 @@ For a well-documented Python package, expect at minimum:
 **Explanation** (at least 1-2):
 - Architecture / design overview
 - Key concepts and terminology
-- Advantages of the chosen tooling and patterns (focus on benefits, not justification)
+- Design decisions / "why" docs
+- Comparison with alternatives (when useful)
 
 ### 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:
+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:
+Canonical Python package nav structure using `pages/` folder-per-quadrant:
 
 ```yaml
 nav:
   - Home: index.md
-  - Getting Started: getting-started.md          # tutorial
+  - Tutorials:                                    # tutorial
+    - Getting Started: pages/tutorials/getting-started.md
   - 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
+    - How to Configure X: pages/how-to/configure-x.md
+    - How to Integrate with Y: pages/how-to/integrate-y.md
+    - Contributing: pages/how-to/contribute.md
   - Reference:                                    # reference
-    - reference/index.md
-    - API Reference: reference/api.md
-    - CLI Reference: reference/cli.md
-    - Configuration: reference/configuration.md
+    - API Reference: pages/reference/api.md
+    - CLI Reference: pages/reference/cli.md
+    - Configuration: pages/reference/configuration.md
   - Explanation:                                  # explanation
-    - explanation/index.md
-    - Architecture: explanation/architecture.md
-  - Contributing: contributing.md                 # how-to (for contributors)
+    - Architecture: pages/explanation/architecture.md
+    - Design Decisions: pages/explanation/design-decisions.md
 ```
 
 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
+- **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
+- **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
+- Use the `mkdocs` skill for site configuration and build concerns — this skill focuses on content structure
 
 ## Output Format
 
@@ -152,16 +152,16 @@ When auditing, also note:
 
 ### Recommended Pages
 #### Tutorials (use `diataxis-tutorial-writer`)
-1. **Getting Started** - Install, first use, verify result [HIGH]
+1. **Getting Started** — Install, first use, verify result [HIGH]
 
 #### How-to Guides (use `diataxis-howto-writer`)
-1. **How to configure X** - ... [HIGH]
+1. **How to configure X** — ... [HIGH]
 
 #### Reference (use `diataxis-reference-writer`)
-1. **API Reference** - Full public API [HIGH]
+1. **API Reference** — Full public API [HIGH]
 
 #### Explanation (use `diataxis-explanation-writer`)
-1. **Architecture Overview** - ... [MEDIUM]
+1. **Architecture Overview** — ... [MEDIUM]
 
 ### Proposed MkDocs Nav
 nav:

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

@@ -25,33 +25,33 @@ Adjacent quadrants share affinities that cause content to bleed across boundarie
 ## 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
+- **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
+- **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)
+- **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)
+- **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
 
@@ -107,13 +107,13 @@ docs/
 ## 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
+- [ ] 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
+- [ ] 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

.github/skills/diataxis-explanation-writer/SKILL.md

@@ -5,16 +5,20 @@ description: Generate understanding-oriented explanation documentation for Pytho
 
 # Diátaxis Explanation Writer
 
-Generate explanation documentation - understanding-oriented discussion that helps the reader make sense of a topic through reflection.
+Generate explanation documentation — understanding-oriented discussion that helps the reader make sense of a topic through reflection.
 
 Explanation is like reading **On Food and Cooking** by Harold McGee: it does not teach you to cook or give you recipes, but it places cooking in context of history, science, and society, deepening your understanding of the craft.
 
+## File Placement
+
+Place explanation pages in `docs/pages/explanation/`. Example: `docs/pages/explanation/concepts.md`.
+
 ## What Explanation Is
 
 - Discursive treatment of a subject that permits reflection
 - Deepens and broadens understanding by providing context, connections, and perspective
 - An answer to "Can you tell me about…?"
-- The only documentation you might read in the bath - away from the keyboard
+- The only documentation you might read in the bath — away from the keyboard
 
 Explanation serves the user's **study**, not their work. It is the counterpart to reference (which also contains propositional knowledge but serves work).
 
@@ -24,7 +28,7 @@ Explanation serves the user's **study**, not their work. It is the counterpart t
 
 - What concept, decision, or aspect of the package would benefit from deeper understanding?
 - Frame it as an implicit "About…": "About the plugin architecture", "About authentication design"
-- Choose a topic that can be meaningfully bounded - not the entire package, but a coherent area
+- Choose a topic that can be meaningfully bounded — not the entire package, but a coherent area
 
 ### Step 2: Gather Context
 
@@ -41,67 +45,82 @@ Structure as a discussion that circles around the topic from different angles. A
 
 ### Make connections
 
-Weave a web of understanding. Connect the topic to other things - even outside the immediate subject - if it helps comprehension.
+Weave a web of understanding. Connect the topic to other things — even outside the immediate subject — if it helps comprehension.
 
 "The event system works similarly to browser DOM events, where handlers are registered for specific event types and called when those events fire."
 
 ### Provide context
 
-Describe the advantages of the approach taken. Focus on what is gained - not on defending the choice or comparing with rejected alternatives. Draw implications. Mention specific examples.
+Explain **why** things are the way they are: design decisions, historical reasons, technical constraints. Draw implications. Mention specific examples.
 
-"SQLite requires zero configuration and ships with Python's standard library. For production workloads exceeding 100 concurrent writers, see the PostgreSQL backend."
+"We chose SQLite as the default backend because it requires zero configuration and ships with Python's standard library. For production workloads exceeding 100 concurrent writers, see the PostgreSQL backend."
 
 ### Talk about the subject
 
-Explanation guides are **about** a topic - they circle around it. The title should allow an implicit "about": "About user authentication", "About the caching strategy".
+Explanation guides are **about** a topic — they circle around it. The title should allow an implicit "about": "About user authentication", "About the caching strategy".
 
 Discuss:
 - The bigger picture
 - History and evolution
 - Choices, alternatives, possibilities
 - Why: reasons and justifications
 
-### State advantages, not justifications
+### Admit opinion and perspective
 
-Describe what the chosen approach provides. Do not include "Why X over Y" sections or comparison tables with alternatives. The reader wants to understand the benefits, not the decision-making process.
+All human creation is invested with opinion. Explanation can and must consider alternatives, counter-examples, and multiple approaches. It is a discussion, not a decree.
+
+"Some teams prefer a monolithic configuration file while others split settings by concern. Both approaches have trade-offs…"
 
 ### Keep explanation closely bounded
 
-One risk of explanation is absorbing other things. The urge to include instruction (how-to) or technical description (reference) is strong. Resist it - those have their own places. Allowing them in interferes with the explanation and removes them from where they belong.
+One risk of explanation is absorbing other things. The urge to include instruction (how-to) or technical description (reference) is strong. Resist it — those have their own places. Allowing them in interferes with the explanation and removes them from where they belong.
 
 ## Language Patterns
 
-- **"The reason for X is because historically, Y…"** - Explain origins
-- **"W is better than Z, because…"** - Offer judgements where appropriate
-- **"An X in this system is analogous to a Y in…"** - Provide context through analogy
-- **"Some users prefer W (because Z). This can be a good approach, but…"** - Weigh alternatives
-- **"X interacts with Y as follows:…"** - Unfold internal workings to build understanding
+- **"The reason for X is because historically, Y…"** — Explain origins
+- **"W is better than Z, because…"** — Offer judgements where appropriate
+- **"An X in this system is analogous to a Y in…"** — Provide context through analogy
+- **"Some users prefer W (because Z). This can be a good approach, but…"** — Weigh alternatives
+- **"X interacts with Y as follows:…"** — Unfold internal workings to build understanding
 
 ## Python Package Explanation Template
 
 ```markdown
 # About [Topic]
 
-[Opening paragraph that frames the topic and its role in the package.]
+[Opening paragraph that frames the topic and why it matters to the reader's
+understanding of the package.]
 
 ## Overview
 
-[High-level description of the concept, system, or approach.
+[High-level description of the concept, system, or decision being explained.
 Connect it to the reader's existing knowledge.]
 
-## [Component/Aspect Name]
+## Why [This Approach]
+
+[Explain the reasoning behind the design. What problem does it solve? What
+alternatives were considered? What constraints shaped the decision?]
 
-[Describe what it does and the advantages it provides.
-Focus on benefits, not on justifying the choice or comparing with alternatives.
-Keep sections concise - state what is gained, not what was rejected.]
+For example, [concrete example that illustrates the concept].
 
 ## How It Works
 
-[Describe the mechanism at a conceptual level - not a step-by-step procedure
+[Describe the mechanism at a conceptual level — not a step-by-step procedure
 (that would be a how-to), but the logic and flow of the system.]
 
 [Diagrams or analogies are valuable here.]
 
+## Trade-offs and Alternatives
+
+[Discuss what was gained and what was given up. Mention alternative approaches
+and why they were not chosen — or when they might be better.]
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| Current approach | ... | ... |
+| Alternative A | ... | ... |
+| Alternative B | ... | ... |
+
 ## Connections
 
 [Link this topic to related concepts, other parts of the system, or broader
@@ -114,11 +133,14 @@ patterns in the ecosystem.]
 
 ## Typical Explanation Pages for Python Packages
 
-- **Architecture Overview** - How the package is structured, the component graph, data flow
-- **Key Concepts** - Domain terminology, mental models, glossary with depth
-- **Plugin/Extension Model** - How extensibility works
-- **Performance Characteristics** - Complexity analysis, caching strategy, benchmarks with context
-- **Security Model** - Trust boundaries, threat model, security approach
+- **Architecture Overview** — How the package is structured, the component graph, data flow
+- **Design Decisions** — Why certain approaches were chosen (ADR-style or narrative)
+- **Key Concepts** — Domain terminology, mental models, glossary with depth
+- **Plugin/Extension Model** — How extensibility works and why it is designed this way
+- **Performance Characteristics** — Complexity analysis, caching strategy rationale, benchmarks with context
+- **Security Model** — Trust boundaries, threat model, why certain security choices were made
+- **Comparison with Alternatives** — How this package differs from similar tools, when to choose which
+- **History and Evolution** — How the package got to its current state (for mature projects)
 
 ## Distinction from Reference
 
@@ -134,10 +156,9 @@ patterns in the ecosystem.]
 
 ## Anti-Patterns to Avoid
 
-- **Disguised reference** - Lists of parameters or API details belong in reference
-- **Disguised how-to** - Step-by-step procedures belong in how-to guides
-- **No clear topic** - Every explanation must be "about" something bounded
-- **Too abstract** - Ground discussion in concrete examples from the actual package
-- **Missing the "why"** - If it does not explain advantages or mechanisms, it is probably reference, not explanation
-- **Justification mode** - "Why X over Y" sections and comparison tables belong in ADRs, not docs
-- **Unbounded scope** - Explanation that tries to cover everything covers nothing well
+- **Disguised reference** — Lists of parameters or API details belong in reference
+- **Disguised how-to** — Step-by-step procedures belong in how-to guides
+- **No clear topic** — Every explanation must be "about" something bounded
+- **Too abstract** — Ground discussion in concrete examples from the actual package
+- **Missing the "why"** — If it does not answer "why", it is probably reference, not explanation
+- **Unbounded scope** — Explanation that tries to cover everything covers nothing well