From doc
Audits, classifies, validates quadrant purity, and scaffolds documentation using Diataxis framework (Tutorials, How-to guides, Reference, Explanation). Useful for doc audits, coverage reports, and classification by type.
npx claudepluginhub joaquimscosta/arkhe-claude-plugins --plugin docThis skill uses the workspace's default tool permissions.
Audit, classify, validate, and scaffold documentation using the [Diataxis](https://diataxis.fr/) framework.
Generates Diataxis four-quadrant docs: tutorials (learn-by-doing), how-to guides (tasks), references (facts), explanations (concepts). For creating, auditing, classifying documentation.
Provides Diataxis four-quadrant docs framework: tutorial/how-to/reference/explanation definitions, classification decision tree, matrix, and signals for content categorization.
Generates Diátaxis-structured software documentation: clarifies needs (type, audience, goal, scope), proposes outlines, writes Markdown tutorials, how-tos, references, explanations.
Share bugs, ideas, or general feedback.
Audit, classify, validate, and scaffold documentation using the Diataxis framework.
# Classify individual files
uv run scripts/diataxis_classify.py docs/*.md
# Audit a docs directory for coverage
uv run scripts/diataxis_audit.py --dir docs
# Validate quadrant purity
uv run scripts/diataxis_validate.py --dir docs
# Scaffold a new Diataxis structure
uv run scripts/diataxis_scaffold.py --dry-run
uv run scripts/diataxis_scaffold.py
| Script | Purpose | Key Flags |
|---|---|---|
diataxis_classify.py | Classify files into quadrants | --json, --verbose, --no-content |
diataxis_audit.py | Coverage report with quality score | --dir, --json, --min-coverage |
diataxis_validate.py | Lint for quadrant purity (DX001-DX010) | --dir, --file, --strict, --json |
diataxis_scaffold.py | Generate folder structure | --layout folders|flat, --init-config, --dry-run |
| Quadrant | Orientation | User State | Folder |
|---|---|---|---|
| Tutorial | Learning | Study + Action | tutorials/ |
| How-to | Task | Work + Action | how-to/ |
| Reference | Information | Work + Cognition | reference/ |
| Explanation | Understanding | Study + Cognition | explanation/ |
Multi-signal weighted scoring (title 30%, headings 25%, content 25%, structure 20%). Documents scoring highly for 2+ quadrants are flagged as "collapsed" with split suggestions.
| ID | Rule | Severity |
|---|---|---|
| DX001 | Tutorial contains reference tables | warning |
| DX002 | How-to has long conceptual preamble | warning |
| DX003 | Reference contains step-by-step instructions | warning |
| DX004 | Explanation contains execution commands | warning |
| DX005 | No clear quadrant signal | info |
| DX006 | Collapsed document (mixed quadrants) | warning |
| DX007 | Tutorial missing prerequisites | info |
| DX008 | Tutorial missing learning objectives | info |
| DX009 | How-to missing problem statement | info |
| DX010 | Reference missing tables | info |
Optional per-project override:
{
"version": 1,
"root": "docs",
"layout": "folders",
"ignore": ["node_modules", ".git", "adr", "rfcs", "*.pdf"],
"custom_signals": {}
}
Create with uv run scripts/diataxis_scaffold.py --init-config.
| Issue | Fix |
|---|---|
uv not found | curl -LsSf https://astral.sh/uv/install.sh | sh or run with python3 scripts/diataxis_classify.py |
| Low confidence on all files | Files may lack quadrant-specific keywords; use --verbose to inspect scores |
| Too many collapsed warnings | Some docs legitimately mix quadrants; consider splitting or accepting |
See TROUBLESHOOTING.md for all error scenarios.