Generate Docs

• 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

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.