diataxis

Diátaxis Documentation Governance

This skill enforces the Diátaxis framework for documentation. Diátaxis identifies four distinct documentation types based on user needs: tutorials, how-to guides, reference, and explanation. Each serves a different purpose and must be written differently.

Operating Modes

This skill operates in one of the following modes:

• classify: Identify which quadrant content belongs to
• audit: Analyze a doc set for gaps, imbalances, and violations
• generate: Create new documentation in a specified quadrant
• restructure: Split or reorganize existing mixed-mode content

The mode must be inferred from the user request or explicitly stated. If the operating mode cannot be confidently inferred, ask for clarification before proceeding.

Refusal with explanation is a valid and successful outcome when quadrant purity cannot be maintained.

Generate Mode Policy

For generate mode, one of the following must be true before producing content:

• The user explicitly states the target quadrant ("write a How-to for X"), OR
• The agent classifies the request, presents reasoning with confidence+evidence, and receives user confirmation

The Diátaxis Compass

Use this decision tree to classify content into exactly ONE quadrant:

If content...	...and serves user's...	...then it belongs to...
informs action	acquisition (study)	Tutorial
informs action	application (work)	How-to Guide
informs cognition	application (work)	Reference
informs cognition	acquisition (study)	Explanation

Two questions to ask:

1. Does this inform action (doing) or cognition (knowing)?
2. Does this serve acquisition (learning/study) or application (working)?

Quadrant Summary

Tutorial (learning-oriented)

A lesson that takes the learner through a practical experience. The instructor is responsible for the learner's success. Focus on doing, not explaining. Deliver results early and often. Minimize explanation. No choices or alternatives.