// Analyzes documentation against Diataxis framework (Tutorial, How-to, Reference, Explanation). Use when reviewing documentation structure or classifying content type. Identifies misalignments between declared category and actual content.
Enforces project documentation style guide compliance for tone, voice, terminology, punctuation, and formatting. Use when checking documentation style or validating MyST/reST syntax. Cites specific style guide violations.
Validates documentation builds successfully. Use when checking Sphinx/RTD build integrity or diagnosing build failures. Reports errors, warnings, and build configuration issues.
Performs comprehensive documentation review including build validation, Diataxis analysis, structure audit, accuracy verification, and style compliance. Use when reviewing documentation changes or auditing documentation quality.
Validates documentation structural integrity including heading hierarchy, metadata, file naming, navigation, and cross-references. Use when checking documentation organization or validating toctree structure.
Verifies documentation accuracy by cross-referencing claims, CLI commands, API signatures, and configuration against source code. Use when validating documentation correctness or checking code-docs consistency. Flags unsupported or outdated claims.
| name | documentation-diataxis |
| description | Analyzes documentation against Diataxis framework (Tutorial, How-to, Reference, Explanation). Use when reviewing documentation structure or classifying content type. Identifies misalignments between declared category and actual content. |
Diataxis classification only: identify whether each page is a tutorial, how-to guide, explanation, or reference; note structural mismatches between content type and declared category, and suggest improvements where real issues exist. Ground classification in the Diataxis foundations: the two axes of craft (action vs cognition, acquisition vs application) define four user needs (learning, goals, information, understanding).
This skill identifies flaws and provides actionable recommendations; it does not enforce compliance or apply pass/fail criteria.
Identify intended category: Determine the declared category
based on directory location
(tutorial/, how-to/, explanation/, reference/)
and file metadata (front matter keys such as category, type,
diataxis, or reST .. meta:: entries).
Infer actual category: Analyse the text's structure, tone, and progression to determine which quadrant it actually resembles. Use these classification criteria:
Tutorial indicators:
How-to guide indicators:
Reference indicators:
Explanation indicators:
Check user need alignment:
Map the page to the user need implied by the action/cognition and acquisition/application axes (learning, goals, information, understanding).
Note hard-to-fit genres: Some documentation types do not align cleanly with a single quadrant (for example, release notes or contributing guides). Flag these cases explicitly, reference the Diataxis guidance on complex hierarchies (https://diataxis.fr/complex-hierarchies/), and choose the closest fit category for reporting.
Evaluate quality:
Functional quality: Is the content accurate, complete, consistent, useful, and precise?
Deep quality: Does the content have good flow? Does it anticipate user questions? Is the cognitive load appropriate? Is the experience clear?
Document misalignments: Explicitly identify where the document fails to meet the needs of its category, jumps between categories, or where quality breaks down. For each issue, provide:
Verify completion: Confirm the analysis completed:
State the completion status:
✓ Diataxis analysis complete: [declared category] → [inferred category], [N] issues found✓ Diataxis analysis complete: Content aligns well with [category]A Diataxis Analysis Report detailing:
If no significant issues are found, state that the documentation aligns well with its intended category.