generate-docs

name	generate-docs
description	Generate documentation with Diátaxis framework. Public APIs must have JSDoc. Every doc lives in one quadrant.

/generate-docs [path]

Generate documentation with Diátaxis quadrant enforcement. Public APIs MUST be documented. Every document MUST live in exactly one quadrant.

No arguments? Describe this skill and stop. Do not execute.

First: Activate Workflow

mkdir -p .claude && echo '{"skill":"doc-code","started":"'$(date -Iseconds)'"}' > .claude/active-workflow.json

Craft Standards (MANDATORY)

Write documentation a master craftsperson would be proud of.

Documentation must look like it was written by a skilled human technical writer, not generated by AI.

AI Antipatterns in Documentation to REJECT

• Restating the obvious (@param name - the name)
• Verbose descriptions that add no information
• Generic placeholder text ("This function handles...")
• Documenting every private/internal detail
• Comments that describe WHAT instead of WHY
• Changelog-style comments in code

Human Craft in Documentation

• Document the WHY, not the obvious WHAT
• Clear examples that show real usage
• Concise descriptions that respect the reader's time
• JSDoc that adds value beyond the type signature
• README sections that help users get started fast

Test: Would someone learn something from this doc they couldn't infer from the code? If not, cut it.

---

Diátaxis Framework

Every document you write or update MUST belong to exactly one quadrant:

                PRACTICAL              THEORETICAL
          ┌──────────────────────┬──────────────────────┐
LEARNING  │     TUTORIALS        │    EXPLANATION        │
          │  "Follow me as I     │  "Here's why this     │
          │   show you how"      │   works this way"     │
          ├──────────────────────┼──────────────────────┤
WORKING   │     HOW-TO           │    REFERENCE          │
          │  "Here's how to      │  "Here's the          │
          │   accomplish X"      │   specification"      │
          └──────────────────────┴──────────────────────┘

Decision Tree

• Learning something new? → Tutorial (hold their hand, no choices)
• Trying to accomplish a task? → How-To (assumes competence, no teaching)
• Looking up specific info? → Reference (complete, consistent, austere)
• Trying to understand why? → Explanation (discuss alternatives, take positions)

Quadrant-to-Output Mapping

Output Type	Quadrant	Rules
JSDoc/TSDoc	Reference	Complete, consistent, example for every public item
README usage sections	How-To	Task-oriented, assumes competence, starts with the goal
docs/tutorials/	Tutorial	Step-by-step, no choices, no theory digressions
Architecture/design docs	Explanation	Discusses why, alternatives, trade-offs

Quadrant-Specific Rules

Reference (JSDoc, API docs):

• Structured by the code, not by tasks
• Consistent format throughout — every function documented the same way
• Include examples for every public item
• No "First, install..." walkthroughs (that's How-To)
• No "why" explanations (that's Explanation)

How-To (README usage, guides):

• Start with the goal ("How to deploy"), not the tool ("Using the deploy command")
• Assumes competence — no teaching
• Numbered steps, troubleshooting section
• No theory digressions

Tutorial (getting-started, walkthroughs):

• Every step explicit, no choices offered
• Reader succeeds at each checkpoint
• Minimal explanation — just enough to proceed
• No "dependency injection is a pattern where..." tangents

Explanation (architecture, design docs):

• Discusses alternatives and trade-offs
• Takes positions — not wishy-washy
• Connects to bigger picture
• Links to relevant How-To and Reference docs

---

⚠️ STRICT REQUIREMENTS - NO JUDGMENT CALLS

You MUST do these documentation tasks. Not "consider" - DO:

1. PUBLIC FUNCTIONS - Add JSDoc/TSDoc to EVERY exported function
2. COMPLEX LOGIC - Add inline comments for non-obvious code
3. README - Update if feature adds new usage/commands
4. TYPES - Document non-obvious type fields

FORBIDDEN (Phase will FAIL if detected):

• Over-documenting obvious code
• Adding comments that just repeat the code
• Saying "documentation would help" without writing it
• Skipping JSDoc on public APIs
• Writing vague descriptions ("handles the thing")
• Mixing Diátaxis quadrants in a single document

Process

1. Analyze — Identify what needs documentation
2. Load Diátaxis — Read .claude/canon/docs/SKILL.md to internalize the full canon (quadrants, anti-patterns, quality checklist)
3. Classify — For each doc being written/updated, determine its Diátaxis quadrant (Tutorial, How-To, Reference, or Explanation). Enforce single-quadrant purity. If a file mixes quadrants, split it or flag it.
4. Document — Write the docs. JSDoc = Reference (complete, consistent, examples). README usage = How-To (task-oriented, assumes competence). Architecture docs = Explanation. Follow quadrant-specific rules above.
5. Audit — Check all documentation against Diátaxis concrete checks:
   • Single quadrant? Each document lives in exactly one quadrant. If it spans two, split it.
   • No teaching in tutorials? Tutorials stick to "do this, then this" without explaining why.
   • No tutorials in reference? Reference avoids "First, install..." walkthroughs.
   • Completeness for reference? Covers every public function/option/parameter — no cherry-picking.
   • Task-oriented how-to? Starts with the goal, not the tool.
6. Report — Output results with Diátaxis audit

REQUIRED Output Format

## Documentation: [target]

DOCUMENTED:
- src/service.ts: 5 functions with JSDoc (Reference)
- src/types.ts: 3 types with field comments (Reference)
- README.md: Added "Usage" section (How-To)

PUBLIC_APIS_DOCUMENTED: N
README_UPDATED: yes/no
COMMENTS_ADDED: N
DIATAXIS_QUADRANTS_CLEAN: yes/no
MIXED_QUADRANT_VIOLATIONS: N

APPLIED:
- [expert]: [decision]

DOC_COMPLETE

Validation (Phase will FAIL if violated)

• No DOCUMENTED section
• PUBLIC_APIS_DOCUMENTED: 0 when public functions exist
• DIATAXIS_QUADRANTS_CLEAN missing from output

🛑 MANDATORY STOP

After documenting:

• DO NOT proceed to any other workflow step
• DO NOT make additional code changes

Your turn ends here. Output DOC_COMPLETE and STOP.