docs-organize-types

name	docs-organize-types
description	Organize related data types into logical categories within sidebars.js. Use this skill to group data types by functionality (e.g., "Collections", "Type System", "Resource Management", "DI & Configuration"). Supports manual categorization (specify types and category) or automatic analysis (scan docs/reference/ and suggest intelligent groupings). The skill updates sidebars.js while preserving existing structure, maintains alphabetical order, and verifies syntax validity.
allowed-tools	Glob, Grep, Read, Edit, Bash

Organize Data Types in Sidebars

Improve documentation structure by organizing related data types into meaningful categories.

Two Modes of Operation

Mode 1: Manual Categorization

When you know exactly which types should go into a category.

Invocation:

docs-organize-types [type1] [type2] [type3] --category "[Category Name]"

Example:

docs-organize-types chunk list vector --category "Collections"

This moves (or creates links for) chunk, list, and vector into a "Collections" category.

Mode 2: Automatic Categorization

When you want the skill to analyze all data types and suggest intelligent groupings.

Invocation:

docs-organize-types --auto

The skill will:

1. Scan docs/reference/ for all data type documentation files
2. Extract type signatures, descriptions, and relationships
3. Analyze integration patterns (which types depend on others)
4. Group types by functional area:
   • Collections: Chunk, List, Vector, etc.
   • Type System: TypeId, Schema, DynamicValue, etc.
   • Resource Management: Resource, Scope, Wire, etc.
   • Context & DI: Context, Wire, etc.
   • Error Handling: SchemaError, Validation, etc.
   • Utilities: MediaType, Syntax, Docs, etc.
5. Suggest category assignments with confidence levels
6. Preview the new sidebars.js structure

Workflow: Manual Mode

Step 1: Validate Input

• Verify each type has a corresponding .md file in docs/reference/
• Confirm the category name is reasonable (avoid duplicates with existing categories)
• If any type is missing, report and stop

Step 2: Check Existing Structure

• Read docs/sidebars.js
• Identify the Reference section
• Check if the category already exists; if so, note its current contents

Step 3: Create/Update Category index.md

Create a new file docs/reference/[category-kebab-case]/index.md with:

---
id: [category-kebab-case]
title: "[Category Name]"
---

## Introduction

[2-3 sentences explaining the category and its purpose]

**Related Types:**
- [`TypeName1`](./<type1>.md) — brief description
- [`TypeName2`](./<type2>.md) — brief description
- [`TypeName3`](./<type3>.md) — brief description

## Overview

[Additional context about how these types work together and when to use them as a group]

Extract descriptions from each type's .md file (first sentence after the opening definition).

Step 4: Update sidebars.js

If the category doesn't exist, create it:

{
  type: "category",
  label: "[Category Name]",
  link: { type: "doc", id: "reference/[category-kebab-case]/index" },
  items: [
    "reference/[category-kebab-case]/[type1]",
    "reference/[category-kebab-case]/[type2]",
    "reference/[category-kebab-case]/[type3]"
  ]
}

If it does exist, append new types in alphabetical order.

Maintain alphabetical order of categories within the Reference section.

Note: Update item paths to include the category subdirectory: "reference/[category-kebab-case]/[type-id]"

Step 5: Verify Syntax

Parse the updated sidebars.js with Node.js to ensure valid JavaScript syntax:

node -c docs/sidebars.js

If there are errors, report and revert.

Step 6: Report Changes

Show:

• Added Category: Yes/No (new category created)
• Index File Created: path to new index.md
• Types Added: list of types moved into the category
• Verification: ✅ Syntax valid | ❌ Syntax error (reverted)
• Preview: before/after snippet of the Reference section

---

Workflow: Automatic Mode

Step 1: Scan Documentation

Use Glob to find all .md files in docs/reference/:

glob("docs/reference/*.md")

Extract the id from each file's frontmatter (line 2, id: <name>).

Step 2: Analyze Type Relationships

For each type file:

Read the file to extract:

• Title (frontmatter title:)
• Definition (opening 1-3 sentences)
• Key features (bullet points, if present)
• Mentions of other types (grep for references: [TypeName](./type-name.md))

Build a relationship graph: if Type A mentions Type B, record that edge.

Step 3: Propose Categories

Based on type names, descriptions, and relationships, assign each type to a category:

Collection Types → Chunk, List, Vector, NonEmptyList, etc.

• Signal: type name contains "chunk" | "list" | "vector" | "sequence" | "collection"
• Context: used for organizing/storing data

Type System & Schemas → Schema, TypeId, DynamicValue, SchemaError, etc.

• Signal: type name contains "schema" | "type" | "dynamic" | "error" | "validation"
• Context: used for type representation, validation, transformation

Resource Management & DI → Resource, Scope, Wire, Finalizer, etc.

• Signal: type name contains "resource" | "scope" | "wire" | "finalizer" | "context"
• Context: used for lifecycle management, dependency injection

Error & Validation → SchemaError, Validation, etc.

• Signal: type name or content mentions error handling, constraints
• Context: used for error representation and validation

Utilities & Formats → MediaType, Syntax, Docs, JSON, XML, etc.

• Signal: type name is format/utility name (not a core abstraction)
• Context: add-on functionality, specific formats

For each proposed grouping, compute a confidence level:

• High (90%+): Clear semantic signal (name + description alignment)
• Medium (70-89%): Some signal (description or relationships align)
• Low (<70%): Weak signal (consider alternatives)

Step 4: Preview Proposed Structure

Show the user:

• Proposed Categories with types grouped and confidence levels
• Before/After snippet of sidebars.js
• Unassigned Types (if any) — types that don't fit well in any category

Step 5: User Confirmation

Wait for user input:

• Accept All: Apply all proposed categories
• Selective: Accept specific categories only
• Reject: Keep current flat structure

Step 6: Create Category index.md Files

For each approved category, create docs/reference/[category-kebab-case]/index.md with:

• Category title and introduction
• List of related types with brief descriptions
• Overview section explaining how types work together

Use the analysis from Step 2 (descriptions and relationships) to write the introduction.

Step 7: Update sidebars.js

Once approved, update sidebars.js with the new structure, maintaining:

• Alphabetical order of categories
• Alphabetical order of types within each category
• Link to category index.md file in category definition
• Existing non-categorized types (if kept)

Step 8: Verify & Report

Same as manual mode: verify syntax, report changes including index.md file creation.

---

Output Format

Summary Report (displayed to user):

✅ Categorization Complete

Added Categories: [N]
- [Category 1]: [type1], [type2], [type3]
- [Category 2]: [type4], [type5]

Modified Categories: [N]
- [Category]: added [type6]

Verification: ✅ Syntax valid

Preview:
  Reference
    ├─ [Category 1]
    │  ├─ chunk
    │  ├─ list
    │  └─ vector
    ├─ [Category 2]
    │  ├─ schema
    │  └─ typeid
    └─ [Uncategorized] (if any)
       └─ mediatype

---

Implementation Notes

• Directory Structure: Each category creates a subdirectory: docs/reference/[category-kebab-case]/
  • Category index: docs/reference/[category-kebab-case]/index.md
  • Type files are organized within the category directory (may involve moving existing files or creating symlinks)
• Index.md Content:
  • Frontmatter with id matching the category kebab-case name
  • Introduction section explaining the category
  • List of related types with descriptions
  • Overview of how types work together
• Sidebar Paths: Updated to reflect category structure: "reference/[category-kebab-case]/[type-id]"
• Category Link: Sidebar category definition includes link: { type: "doc", id: "reference/[category-kebab-case]/index" }
• Alphabetical order is maintained within each category and at the category level
• Existing categories are preserved if they already exist in sidebars.js
• Syntax validation is mandatory — invalid changes are reverted
• No breaking changes — existing structure is preserved; only new categories are added

---

Common Failures

Symptom	Likely cause	Fix
node -e "require('./docs/sidebars.js')" reports a syntax error	Edit introduced an unmatched brace, trailing comma in unsupported syntax, or stray quote.	Revert the edit and reapply more carefully. Validate after each insertion before moving on.
Docusaurus build complains "Doc id ... not found"	A type was added to a category but the file at docs/reference/<id>.md doesn't exist.	Confirm every sidebar entry corresponds to a real file. Either create the missing page first, or remove the entry.
The same type appears in two categories	Auto-categorization fired twice, or a manual entry was added without removing the old one.	Sidebar entries must be unique. Pick the better-fitting category, remove the other entry.
Category link 404s in Docusaurus	link: { type: "doc", id: "reference/<cat>/index" } set but index.md is missing.	Either create docs/reference/<cat>/index.md (recommended for hierarchical layout) or omit the link field.
Type that doesn't fit any obvious category	Genuinely cross-cutting type (e.g., a utility used by many categories).	Stop and ask the user. Don't force a fit; cross-cutting types often belong in their own "Utilities" category.
Edit duplicated existing structure (no diff)	Skill ran in idempotency-check mode but produced no change.	Confirm with git diff sidebars.js — if empty, the structure was already correct. Report and exit.