Arkhe-claude-plugins diataxis

install

source · Clone the upstream repo

git clone https://github.com/joaquimscosta/arkhe-claude-plugins

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/joaquimscosta/arkhe-claude-plugins "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/doc/skills/diataxis" ~/.claude/skills/joaquimscosta-arkhe-claude-plugins-diataxis && rm -rf "$T"

manifest: plugins/doc/skills/diataxis/SKILL.md

source content

Diataxis Documentation Framework

Audit, classify, validate, and scaffold documentation using the Diataxis framework.

Quick Start

# 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

Capabilities

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`

The Four Quadrants

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/`

Classification Algorithm

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.

Validation Rules

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

Config File (.diataxis-config.json)

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

Common Issues

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.

References

WORKFLOW.md — Full methodology (discover, classify, audit, validate, scaffold)
EXAMPLES.md — Real-world examples for all operations
TROUBLESHOOTING.md — Error handling and debugging tips
Diataxis framework — Official documentation