feat(trogonstack-diataxis): make documentation easier to write and maintain

plugins/trogonstack-diataxis/README.md

@@ -1,7 +1,9 @@
 # trogonstack-diataxis
 
-Documentation skills following the Diataxis framework for organizing and generating docs into tutorials, how-to guides, reference, and explanation sections.
+Diataxis guidance for writing and organizing documentation around the reader's needs.
 
 ```bash
 claude plugin install trogonstack-diataxis@trogonstack
-```
+```
+
+Use [diataxis-write-docs](skills/diataxis-write-docs/SKILL.md) to draft or revise documentation for its intended audience. Use [diataxis-organize-docs](skills/diataxis-organize-docs/SKILL.md) to classify, split, or relocate existing material and maintain its navigation.

plugins/trogonstack-diataxis/skills/diataxis-organize-docs/SKILL.md

@@ -8,9 +8,9 @@ allowed-tools:
 
 # Diataxis Documentation Organization
 
-Reorganize documentation by classifying content into the four Diataxis quadrants and creating a structured documentation hierarchy.
+Reorganize documentation by classifying content into the Diataxis categories and creating a structured documentation hierarchy.
 
-## The Four Quadrants
+## Documentation Categories
 
 | Quadrant | Orientation | Purpose | User Need |
 |----------|-------------|---------|-----------|
@@ -19,25 +19,13 @@ Reorganize documentation by classifying content into the four Diataxis quadrants
 | **Reference** | Information | Describe the machinery | "I need facts about Y" |
 | **Explanation** | Understanding | Clarify concepts | "I want to understand why" |
 
-## Step 1: Analyze Existing Documentation
+## Directory Structure
 
-Scan the documentation directory and classify each file or section:
+Organize docs into this hierarchy, adding topic subdirectories as needed:
 
-```
-For each document/section, determine:
-- Does it walk through steps to learn? → Tutorial
-- Does it solve a specific problem? → How-to
-- Does it describe APIs/configs/specs? → Reference  
-- Does it explain concepts/rationale? → Explanation
-```
-
-## Step 2: Create Directory Structure
-
-Organize docs into this hierarchy:
-
-```
+```text
 docs/
-├── tutorials/           # Learning-oriented
+├── tutorial/            # Learning-oriented
 │   ├── getting-started/
 │   └── {topic}/
 ├── how-to/              # Task-oriented
@@ -54,191 +42,29 @@ docs/
 └── README.md            # Navigation hub
 ```
 
-## Step 3: Classification Criteria
-
-### Tutorials (Learning)
-
-**Characteristics:**
-- Step-by-step instructions for beginners
-- Builds toward a working example
-- Focuses on "what the user does"
-- Has a concrete end goal
-
-**Example titles:**
-- "Your First Application"
-- "Getting Started with X"
-- "Building a Sample Project"
-
-**DO NOT include:**
-- Exhaustive options or configurations
-- Theoretical explanations
-- Edge cases
-
-### How-to Guides (Tasks)
-
-**Characteristics:**
-- Assumes basic knowledge
-- Addresses a specific problem
-- Provides actionable steps
-- May have multiple valid approaches
-
-**Example titles:**
-- "How to Deploy to Production"
-- "Migrating from v1 to v2"
-- "Configuring Authentication"
-
-**DO NOT include:**
-- Teaching fundamentals
-- Complete API documentation
-- Philosophical discussions
-
-### Reference (Information)
-
-**Characteristics:**
-- Accurate and complete
-- Consistent structure
-- Describes what IS (not how to use)
-- Dry, factual tone
-
-**Example content:**
-- API endpoints and parameters
-- Configuration options
-- CLI commands and flags
-- Data schemas
-
-**DO NOT include:**
-- Explanations of why
-- Step-by-step tutorials
-- Opinions or recommendations
-
-### Explanation (Understanding)
-
-**Characteristics:**
-- Discusses context and background
-- Explains design decisions
-- Connects concepts together
-- Can be discursive
-
-**Example titles:**
-- "Understanding the Event Loop"
-- "Why We Chose X over Y"
-- "Architecture Overview"
-
-**DO NOT include:**
-- How-to instructions
-- Reference specifications
-- Beginner tutorials
-
-## Step 4: Split Mixed Documents
-
-When a document contains multiple types:
-
-1. **Identify boundaries** - Mark where content shifts purpose
-2. **Extract sections** - Move each type to its proper location
-3. **Add cross-references** - Link related content across quadrants
-4. **Preserve context** - Ensure each piece stands alone
-
-### Example Split
-
-**Before (mixed document):**
-```markdown
-# Authentication
-
-Authentication uses JWT tokens. (explanation)
-
-## Quick Start
-1. Install the package... (tutorial)
-
-## API Reference
-- `authenticate(user, pass)` - Returns token (reference)
-
-## Troubleshooting
-### Token Expired
-If you see error X, do Y... (how-to)
-```
-
-**After (split):**
-```
-tutorials/authentication-quickstart.md
-how-to/troubleshooting/token-expired.md
-reference/api/authentication.md
-explanation/concepts/authentication.md
-```
-
-## Step 5: Create Navigation Index
-
-Always use `README.md` as the root navigation file — never `index.md`.
+Always use `docs/README.md` as the root navigation file, never `index.md`.
 
-Build a documentation hub that helps users find content by their need:
+## Writing Conventions
 
-```markdown
-# Documentation
+Keep skill instructions and generated documentation free of manually maintained totals and numbered section references. Use descriptive headings and named links. For ordered procedures, write each Markdown list marker as `1.` so the renderer maintains numbering. Preserve numeric facts that are necessary to understand or use the subject.
 
-## Learning
-New here? Start with our tutorials:
-- [Getting Started](tutorials/getting-started.md)
-- [Your First App](tutorials/first-app.md)
+## Workflow
 
-## Guides
-Solve specific problems:
-- [Deployment](how-to/deployment/)
-- [Troubleshooting](how-to/troubleshooting/)
+Load only the references needed for the current task:
 
-## Reference
-Technical specifications:
-- [API Reference](reference/api/)
-- [Configuration](reference/configuration/)
+1. **Analyze existing content.** Classify each file or section by the reader's need. Read [classification criteria](references/classification.md) when classifying existing content or resolving ambiguous categories.
+1. **Map the structure.** Assign content to the hierarchy above and identify which documents to keep, move, or split.
+1. **Separate mixed documents.** When a document serves multiple purposes, read [splitting guidance](references/splitting.md) for the migration procedure and example. Preserve context and link related content across quadrants.
+1. **Build navigation.** When creating or updating the documentation hub, read [navigation guidance](references/navigation.md) for its template. Update links affected by moved or split content.
+1. **Verify and report.** Apply the completion checks below. For an audit, report the current state, classifications, proposed file placements, and needed cross-references. For completed edits, summarize the changes and verification. Scale the report to the task.
 
-## Understanding
-Deep dives and background:
-- [Architecture](explanation/architecture.md)
-- [Design Decisions](explanation/decisions/)
-```
+## Completion Checks
 
-## Quality Checklist
-
-After reorganization, verify:
-
-- [ ] Each document serves ONE purpose
+- [ ] Each document serves one purpose
 - [ ] Tutorials have clear learning outcomes
 - [ ] How-to guides solve specific problems
 - [ ] Reference is complete and accurate
 - [ ] Explanations provide genuine insight
-- [ ] Cross-references connect related content
-- [ ] Navigation makes user intent clear
-- [ ] No orphaned or duplicated content
-
-## Anti-Patterns to Fix
-
-| Problem | Solution |
-|---------|----------|
-| Tutorial with exhaustive options | Move options to reference, link to it |
-| How-to explaining fundamentals | Extract to tutorial, assume knowledge |
-| Reference with usage examples | Move examples to how-to |
-| Explanation with code snippets | Keep only conceptual snippets |
-| One giant README | Split into proper quadrants |
-
-## Output Format
-
-After analysis, report:
-
-```markdown
-## Documentation Audit
-
-### Current State
-- Total documents: X
-- Mixed documents: Y
-- Missing quadrants: [list]
-
-### Classification Results
-| Document | Current Type | Recommended Type | Action |
-|----------|--------------|------------------|--------|
-| ... | ... | ... | Split/Move/Keep |
-
-### Proposed Structure
-[Directory tree with file placements]
-
-### Cross-References Needed
-- [doc A] should link to [doc B]
-- ...
-```
+- [ ] Cross-references connect related content and resolve after moves
+- [ ] `docs/README.md` makes user intent clear
+- [ ] No orphaned, duplicated, or lost content

plugins/trogonstack-diataxis/skills/diataxis-organize-docs/references/classification.md

@@ -0,0 +1,103 @@
+# Classification Criteria
+
+Classify each document or section by its purpose:
+
+- Does it walk through steps to learn? Tutorial.
+- Does it solve a specific problem? How-to.
+- Does it describe APIs, configurations, or specifications? Reference.
+- Does it explain concepts or rationale? Explanation.
+
+## Tutorials (Learning)
+
+**Characteristics:**
+
+- Step-by-step instructions for learners
+- Builds toward a working example
+- Focuses on "what the user does"
+- Has a concrete end goal
+
+**Example titles:**
+
+- "Your First Application"
+- "Getting Started with X"
+- "Building a Sample Project"
+
+**DO NOT include:**
+
+- Exhaustive options or configurations
+- Theoretical explanations
+- Edge cases
+
+## How-to Guides (Tasks)
+
+**Characteristics:**
+
+- Assumes basic knowledge
+- Addresses a specific problem
+- Provides actionable steps
+- May have multiple valid approaches
+
+**Example titles:**
+
+- "How to Deploy to Production"
+- "Migrating from v1 to v2"
+- "Configuring Authentication"
+
+**DO NOT include:**
+
+- Teaching fundamentals
+- Complete API documentation
+- Philosophical discussions
+
+## Reference (Information)
+
+**Characteristics:**
+
+- Accurate and complete
+- Consistent structure
+- Describes interfaces, behavior, and constraints
+- Dry, factual tone
+
+**Example content:**
+
+- API endpoints and parameters
+- Configuration options
+- CLI commands and flags
+- Data schemas
+
+**DO NOT include:**
+
+- Explanations of why
+- Step-by-step tutorials
+- Opinions or recommendations
+
+## Explanation (Understanding)
+
+**Characteristics:**
+
+- Discusses context and background
+- Explains design decisions
+- Connects concepts together
+- Can be discursive
+
+**Example titles:**
+
+- "Understanding the Event Loop"
+- "Why We Chose X over Y"
+- "Architecture Overview"
+
+**DO NOT include:**
+
+- How-to instructions
+- Reference specifications
+- Learning walkthroughs
+
+## Anti-Patterns to Fix
+
+| Problem | Solution |
+|---------|----------|
+| Tutorial with exhaustive options | Move options to reference, link to it |
+| How-to explaining fundamentals | Extract to tutorial, assume knowledge |
+| Reference with a task walkthrough | Move the walkthrough to how-to; keep concise usage examples |
+| Explanation dominated by procedural code | Move the procedure to how-to; keep snippets that clarify concepts |
+| One giant README | Split into proper quadrants |