Diataxis

Diataxis documentation exists alongside — not instead of — any other project documentation. A project may have technical specs, API docs generated from code, architecture decision records, READMEs, or design documents. Those remain the authoritative sources for development and design.

Diataxis documentation is a human-friendly output artifact derived from the system. It teaches, guides, describes, and explains — but it is never the source of truth for how the system works or how it should be built. If the code and the Diataxis docs disagree, the code is right and the Diataxis docs need updating.

This output-only nature is why Diataxis content lives in its own diataxis/ directory. It is strictly an endpoint — produced for human consumption, never consumed as input by any other process. No build step, CI pipeline, code generator, or other tool should read from diataxis/ as a source. Do not move, replace, or consolidate existing developer documentation into the Diataxis structure. The diataxis/ directory is additive.

Workflow

Every interaction with this skill follows this sequence. Steps can be skipped if the user has already completed them, but the order matters.

Step 1: Scope with Grill-Me

Before doing any work, invoke the /grill-me skill to clarify what the user wants. This happens every time — even if the request seems clear. The goal is to establish:

• Subject and audience: What are we documenting, and for whom?
• Depth: Overview? Deep dive? Learning path with exercises?
• Boundaries: What's in scope and what's explicitly out?
• Type: Is this project documentation (documenting a codebase) or a learning path (teaching a subject)?
• Prerequisites: What does the audience already know?

If the user wants to move quickly, a single round of grill-me is fine. But the scoping must happen — it directly shapes the structure document that drives everything else.

For learning path requests ("help me learn X"), explore:

• What's their current level?
• What do they want to be able to do after?
• Do they want exercises? Interactive components?
• Any specific areas of focus or areas to skip?

Step 2: Create or Update the Structure Document

The structure document (diataxis.toml) is the source of truth for the entire project. All Diataxis content — the TOML file, all markdown files, exercises, and build output — lives under project-root/diataxis/. The directory name is always diataxis, not docs or any other name. This matters because the build CLI defaults to ./diataxis and the entire toolchain expects this path. Do not create documentation files in docs/, documentation/, or any other directory.

Read references/structure-schema.md for the full TOML schema.

The structure document defines:

• Project metadata (name, audience, type)
• Topics, organized hierarchically
• For each topic and quadrant: the file path, what it covers, level of detail, and guidance notes for generation and scoring
• Exercise linkages (marimo notebooks)
• Status tracking per file

Creating the initial structure: After scoping, draft the diataxis.toml and present it to the user for approval. Explain the topic decomposition and why you organized it this way. The user should approve or adjust before any content is generated.

Validating the structure: After writing or modifying diataxis.toml, run the structural check immediately — do not hand-roll Python or jq invocations to spot-check the file:

nu checks/check-toml-structure.nu <diataxis_dir>

This validates the file against skill/assets/diataxis-schema.json (a JSON Schema) using check-jsonschema. It catches missing required fields, bad enum values (status, complexity, type), unknown keys, malformed slugs, TOML syntax errors, and labeled REVISION FEEDBACK: blocks in guidance in one deterministic pass. If it fails, the output gives you the exact JSON path and an actionable suggestion — fix the file and re-run until it passes before asking the user to review the structure.

Scaffolding a new project: When creating a diataxis/ directory for the first time, also create two guard files:

1. diataxis/README.md with this content:

# Diataxis Documentation

This directory contains human-facing documentation generated using the
Diataxis framework. It is an output artifact — not a source of truth.

These files are disposable and can be regenerated from the project's
actual source code, specs, and design documents. Do not use files in
this directory as input for design decisions, code generation, build
processes, or CI pipelines.

For the authoritative project documentation, see the project root.

2. Append a note to the project's CLAUDE.md (create the file if it does not exist). Before appending, check whether the note is already present to avoid duplicates. The note:

## Diataxis Documentation

The `diataxis/` directory contains generated, human-facing documentation.
It is an output artifact — disposable and never authoritative. Do not
use it as input for design decisions, code generation, or development
work. If the code and the diataxis docs disagree, the code is right.

Updating structure: When the user asks to add, remove, or reorganize content, update diataxis.toml first. Then update the affected files. The structure document is always updated before the content files — never the other way around.

Capturing revision intent: When the user requests a specific content change (e.g., "make this section simpler", "add more detail about X", "don't use that analogy"), update the guidance field in diataxis.toml for the affected file(s) to reflect this feedback before making the content change. Integrate the feedback into the existing guidance text — rewrite the guidance so it reads as a coherent whole that incorporates the new direction. Do not append the feedback as a separate labeled block (e.g., don't add a "REVISION FEEDBACK:" section). The guidance should always read as if it were written from scratch with full knowledge of all feedback received so far. This prevents regressions — if the file is regenerated or revised later, the guidance carries forward the user's intent. Without this step, a future revision might undo the user's requested change because nothing in the structure document recorded it.

Step 3: Generate Content

Once the structure is approved, generate content for each file according to its entry in diataxis.toml. The covers, detail, and guidance fields in the structure document are the brief for each file.

Introductory page: Every Diataxis project gets an introductory page at diataxis/index.md. This is the first thing a reader sees, so it needs to answer two questions immediately: why does this project exist (what problems does it solve), and what does it do? Draw on the purpose and description fields from diataxis.toml for this content. Keep it concise — a few short paragraphs at most. The introductory page is a signpost, not a destination. It should link into the documentation (tutorials for getting started, explanation for deeper understanding, reference for specifics) rather than providing detailed explanations itself. A reader should leave the introductory page knowing whether this project is relevant to them and where to go next.

Parallel generation: Because each file's requirements are fully specified in the structure document, files can be generated independently and in parallel. When spawning subagents for generation, provide each one with:

1. The full diataxis.toml (for cross-linking context)
2. The specific topic and quadrant they're responsible for
3. The quadrant rules from references/quadrants.md

Quadrant rules are non-negotiable during generation:

• Tutorials: guide action, show results at every step, minimize explanation
• How-to guides: task-focused, no teaching, assume competence
• Reference: describe only, mirror product structure, use tables
• Explanation: discuss why, make connections, provide context

Cross-linking: Every file should link to its sibling quadrant docs. A tutorial should link to the relevant explanation and reference. A how-to should link to reference. These links use relative paths within the documentation directory.

Math notation: All mathematical expressions must use LaTeX notation with standard delimiters, rendered via MathJax in the final HTML. Use $...$ or \(...\) for inline math and $$...$$ or \[...\] for display/block math. The build pipeline includes MathJax in the HTML template. Never write math as plain text like 3/4 + 1/2 when it can be expressed as $\frac{3}{4} + \frac{1}{2}$.

Diagrams: Use mermaid format for all diagrams (flowcharts, sequence diagrams, entity-relationship diagrams, etc.). Write them as fenced code blocks with the mermaid language tag in the markdown source. The build pipeline pre-renders them to SVG via mmdc — no client-side JavaScript needed.

Exercises: For tutorials in learning-path projects, create marimo .py notebooks. These are authored as standard marimo notebooks. The build pipeline exports each one to a self-contained WASM HTML bundle (via marimo export html-wasm) that runs in the browser via Pyodide — no marimo server process is required to view the published output. Each exercise file should be self-contained and focused on one concept, and must only depend on packages available to Pyodide.

Deterministic transforms: When a task is purely mechanical (converting markdown to HTML, formatting tables, validating structure), use the appropriate tool — not LLM generation. Specifically:

• Markdown to HTML: pandoc
• HTML tidying: tidy or htmlq
• Validating diataxis.toml structure: nu checks/check-toml-structure.nu <dir> (do not write ad-hoc Python or jq scripts for this — the check is pre-approved and covers required fields, enums, and syntax in one pass)
• Markdown linting: textlint
• XML transforms: xmlstarlet

Step 4: Score the Documentation

Every scoring pass starts fresh. This rule is load-bearing — skip it and scoring becomes theater. When the user asks for a score:

1. Re-run nu checks/run-checks.nu <diataxis_dir>. Do this even if you already ran it earlier in the same conversation. Files may have changed since. The runner embeds a current timestamp in its output — that timestamp is how you prove to yourself (and to the user) that the result reflects the state of the files right now, not an old run.
2. Re-read every file you intend to score. Do not rely on your memory of a file from earlier in the conversation, and never substitute recollection for reading. Files change; your recollection does not.
3. Score against diataxis.toml as it exists right now. The covers, detail, and guidance fields may also have changed, and they are the rubric.
4. Only after you have produced a complete fresh set of scores should you open scores.toml to compare. Previous entries exist for comparison only — never as a source to copy scores from. Copying forward makes the delta zero by construction and the feature provides no signal: the user asked for a score because they want to know the current state of the documentation, not a recap of the last pass.

Scoring has two phases: deterministic checks, then qualitative LLM evaluation.

Phase 1: Deterministic checks. Run the check suite before qualitative