Diataxis

Diátaxis

Reference: https://diataxis.fr

The four modes are the meta-framework the artifact skills sit inside. This skill forces the mode pick the artifact skills assume. Pick one mode per document before writing; a doc that needs two modes is two documents.

Cheapest layer first

Doc work escalates up the user-CLAUDE.md ladder; reach for a Diátaxis doc only when the cheaper layer can't carry the knowledge:

inline comment → docstring → Diátaxis doc → repo-local CLAUDE.md → ~/.claude/CLAUDE.md.

A non-obvious why is a comment. An interface contract is a docstring. Reach a docs/ artifact only for knowledge shared across the project that no closer layer holds.

Defer to the artifact skills

readme, contributing, adr, changelog own their specific artifacts. This skill owns the meta-mode for everything else under docs/. When both could apply, the artifact skill wins — a README is a README, not a "reference doc."

Pick the mode

Two axes: action vs cognition (do something / understand something), acquisition vs application (studying / working).

Smell test before writing: is the reader learning, doing, looking up, or understanding? One answer. If two, split the doc.

Tutorial

• Purpose — a lesson. The reader ends able to do the thing, having done it once under guidance.
• Audience — a newcomer with no prior context; assume nothing.
• Shape — a single guaranteed-success path, concrete and hand-held. Author owns every step; the reader only follows.
• Anti-patterns
  • Over-explaining mechanics — why belongs in explanation; the tutorial just has the reader do it.
  • Assuming the reader will deviate or offering branches — one path, no choices.
  • Reference-style completeness — list only what this lesson touches, not every option.
  • Leaving a step that can fail on a clean machine — a tutorial that doesn't reproduce isn't a lesson.

How-to

• Purpose — a recipe to reach a goal the reader already has.
• Audience — a competent practitioner who knows what they want and needs the steps, not the background.
• Shape — an ordered series of actions. Imperative. Starts at a realistic precondition, ends at the goal.
• Anti-patterns
  • Narrating wrapper/tool internals — the reader runs the command, they don't need its call graph.
  • Restating idempotence or guarantees already in source comments — if the code says it, the how-to doesn't.
  • Predicting self-describing prompts or output — don't transcribe what the tool already tells the operator on screen.
  • Explanatory prose wrapped around code blocks ("documentation poetry") — if a paragraph doesn't change what the reader types, cut it. (Primary motivating failure.)

Reference

• Purpose — describe the machinery so the reader can look up a fact and trust it.
• Audience — a practitioner mid-task who needs an authoritative answer fast.
• Shape — dry, structured, consistent. Mirror the code's own structure (one section per command/flag/field). Complete within scope.
• Anti-patterns
  • Narrative connective tissue — no "now that we've seen X, let's…"; entries stand alone.
  • Opinionated commentary or recommendations — state what is, not what you'd choose; advice belongs in how-to or explanation.
  • Selective coverage — partial reference is a trap; if it's in scope, document it or say it's out of scope.

Explanation

• Purpose — illuminate the why: context, background, the shape of the decision space.
• Audience — someone studying the topic away from the keyboard, building a mental model.
• Shape — discursive prose. Free to discuss alternatives, history, trade-offs, opinions (owned as opinions).
• Anti-patterns
  • Drifting into runnable commands or step lists — link the how-to, don't inline it.
  • Ending with a recipe — if it tells the reader what to do next, that's a how-to wearing an explanation's clothes.
  • Pretending to be neutral reference — explanation takes positions; own them rather than disguising them as fact.

Procedure

1. Confirm the artifact isn't a README/CONTRIBUTING/ADR/CHANGELOG — if it is, hand off to that skill.
2. Run the smell test; name the single mode. If the doc wants two, surface the split before writing.
3. Draft against that mode's shape; check the draft against its anti-patterns before claiming done.
4. On an edit, first classify the existing doc's mode, then flag any prose that belongs to a different mode (the drift this skill exists to catch).