name: diataxis description: > ALWAYS use this skill if the user requests diataxis documentation. This includes creating, updating, reviewing, scoring, or publishing diataxis-structured content. allowed-tools:

• Bash(nu checks/run-checks.nu *)
• Bash(nu checks/check-toml-structure.nu *)
• Bash(python skill/scripts/upgrade_to_hugo.py *)

Diataxis Documentation Skill

This skill manages documentation projects structured around the Diataxis framework. It handles the full lifecycle: scoping, structuring, authoring, scoring, revising, and publishing.

Core Concepts

Diataxis organizes documentation into four quadrants based on two axes:

Each quadrant serves a different user need and has strict rules about what belongs in it. The power of Diataxis comes from keeping these quadrants distinct — content that bleeds across boundaries degrades the documentation.

A fifth, optional section — Exercises — appears when the project includes marimo notebooks. It sits alongside the four quadrants as a showcase surface: an index of the project's interactive notebooks, grouped so a reader can find them without first threading through the tutorials they attach to. Exercises is conditional by design — a project with no marimo notebooks has no Exercises section, and the top-level nav correctly reflects that. See "Exercises (optional fifth section)" below for the full rule.

Presentation order: the published site presents the quadrants as Explanation → Tutorials → How-to Guides → Reference, with Exercises appended at the end when the project has marimo notebooks. Explanation comes first so readers encounter the conceptual framing before the mechanics. Tutorials and How-to guides follow for readers ready to act. Reference sits after them as the lookup surface. Exercises, when present, comes last: it is a browsing aid for readers who want to see the thing working before or after committing to a tutorial. This ordering is enforced by the reviewer (nu checks/run-checks.nu) via _index.md section weights.

Read references/quadrants.md for the detailed rules governing each quadrant type, including the Exercises section.

Exercises (optional fifth section)

When the project has any marimo notebooks under exercises/, create an examples/_index.md landing page with title = "Exercises" and weight = 50. Its body is a short introduction plus a bulleted, topic-grouped list linking to every /exercises/<stem>/ bundle in the project. Give each entry a one-line description drawn from the tutorial that owns it (its covers and description), so the landing page reads as an answer to "what can I play with here?" rather than a raw directory listing. The source directory stays named examples/ (to avoid colliding with the exercises/*.py source tree) while the nav label the reader sees is "Exercises", matching the content type.

Two rules keep the section honest:

• Conditional existence. No exercises/*.py files → no _index.md under examples/, no top-nav entry. The reviewer treats the absence as correct in that case. This is why the Hugo mount for examples/ is always present in hugo.toml but the landing page is not: an empty mounted directory does not render a section.
• No separate per-example content files. The marimo WASM bundles at /exercises/<stem>/ are the content. The Exercises section is an index page, not a duplicate of the notebooks. Do not author examples/<stem>.md files — they would diverge from the notebooks and the tutorials, and the skill would have no way to keep all three in sync.

When a tutorial's exercises list changes (a new entry added, an old one removed or renamed), regenerate examples/_index.md in the same change so the landing page does not drift from reality.

Relationship to Other Documentation

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 published Hugo site builds against this directory. Do not create documentation files in docs/, documentation/, or any other directory.

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

Detect the project state first. Before touching anything, figure out which of three states the target diataxis/ directory is in — the path branches from here:

1. Absent or empty — no diataxis/ directory, or one that contains no diataxis.toml. This is a new project. Skip ahead to "Scaffolding a new project" below.
2. Pre-Hugo format, or ported from another publishing tool — a diataxis/ directory authored under an earlier version of this skill, or imported from Jekyll, MkDocs, Docusaurus, GitBook, Sphinx, or similar. You will see one or more of: no hugo.toml alongside diataxis.toml; no Makefile or go.mod; quadrant markdown files that start with an ATX H1 (# Title) instead of a +++-delimited frontmatter block; no _index.md inside any quadrant directory; a stray index.md inside any quadrant directory (see "_index.md vs index.md" below); internal links targeting .html files. Upgrade it before doing any other work — see the next subsection.
3. Current Hugo format — hugo.toml is present, quadrant files begin with +++ frontmatter, and each quadrant directory has an _index.md. Proceed with the normal add/update flow below.

Confirm the state by running the detection pass — it is fast and deterministic:

python skill/scripts/upgrade_to_hugo.py <diataxis_dir> --check

Exit status 1 means a pre-Hugo project was detected; 0 means the directory is already Hugo-format (or brand new).

Upgrading a pre-Hugo project: when detection reports a pre-Hugo project, run the upgrade script before generating, scoring, or revising any content:

python skill/scripts/upgrade_to_hugo.py <diataxis_dir>

The script is idempotent and only touches files that need migrating. It scaffolds hugo.toml/Makefile/go.mod if missing, prepends TOML frontmatter to every quadrant markdown file (title from the file's body H1, weight from topic.order * 10 + quadrant_weight, topic/covers/ detail from the matching diataxis.toml entry), drops the body H1, rewrites .html links to Hugo pretty-URL directory form, adds a [cascade] table to index.md, renames stray <quadrant>/index.md files to _index.md (preserving the body and adding frontmatter if missing), and creates the four _index.md quadrant landing pages with canonical section weights. Read references/hugo-migration.md for the full catalog of what the upgrade does and does not do.

_index.md vs index.md. Hugo treats a section directory that contains index.md (no underscore) as a leaf bundle — one page plus attachments — and silently hides every other file in the directory. So tutorials/index.md, the convention in Jekyll, MkDocs, Docusaurus, and most wiki-style tools, will break the Tutorials section: every tutorial file on disk stops appearing on the section page. The landing page in a Hugo section must be _index.md (with the underscore). The upgrade script detects stray <quadrant>/index.md files and renames them. The rule only applies to subdirectories; the root diataxis/index.md is correct — hugo.toml mounts it to content/_index.md at build time.

After the script finishes, do two things before you continue:

1. Read the retired-tool report it printed. guidance fields that mention pandoc, mmdc, uv run diataxis build, or diataxis/_build/ need to be reworked through the skill's revision workflow (Step 5): integrate the new direction into the existing guidance text, then regenerate the affected file. Do not rewrite those guidance fields silently — the author's intent is encoded there, and the skill's feedback-integration rule still applies.
2. Run nu checks/run-checks.nu <diataxis_dir>. Every structural check should pass. If any fail, fix the underlying file and re-run — do not re-run the upgrade script expecting different output; it is idempotent and will not revisit files it already upgraded.

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, do all of the following:

1. Create 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.

1. 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.

1. Copy the publishing scaffolds from skill/templates/ into the diataxis/ directory so the user can run make build as soon as content is generated:

   • skill/templates/Makefile → diataxis/Makefile (no substitution)
   • skill/templates/hugo.toml → diataxis/hugo.toml; replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with the values from [project] in the structure document
   • skill/templates/go.mod → diataxis/go.mod; replace {{MODULE_PATH}} with diataxis.local/<project-slug> where the slug is the lowercased project name with non-alphanumeric runs collapsed to hyphens

   These are publishing config — user-owned from the first build onward. Once scaffolded, the skill must not rewrite them. If a file already exists at the target path, skip it.

2. Create an empty diataxis/examples/ directory alongside the four quadrant directories. The mount for examples/ in hugo.toml is always declared (so a project can add exercises later without editing config), and Hugo logs a warning if that mount points at a nonexistent source. An empty directory — with or without an _index.md inside — silences the warning and lets the presence of _index.md alone control whether the Exercises section renders. Adding the _index.md itself is Step 3's job, gated on whether the project has any exercises/*.py.

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.

Include a ## Sections list on the homepage that links to every top-level section: the four quadrant landing pages (tutorials/, howto/, reference/, explanation/) and — when the project has any exercises/*.py notebooks — the Exercises landing page (examples/). The homepage list mirrors the sidebar nav; omitting Exercises when notebooks exist leaves the main landing page out of sync with the sidebar and hides the gallery from readers who arrive via the home page. Use the same Hugo directory-form URLs as the sidebar (tutorials/, not tutorials/_index.md).

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:

• Explanation: discuss why, make connections, provide context
• 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

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. Link targets use Hugo pretty-URL directory form (/tutorials/first-project/, never .md or .html).

The resolution rules are not intuitive because Hugo publishes tutorials/foo.md at the URL /tutorials/foo/ (one level deeper than the source file), and the browser resolves every relative link against that trailing-slash URL per RFC 3986. Writing cross-quadrant links "the way the source tree looks" produces 404s. The guidance below gets it right; references/link-resolution.md explains why.

Prefer absolute paths for cross-quadrant links. Because hugo.toml sets relativeURLs = true, Hugo rewrites absolute URLs to the correct form for each page at build time. Authors who use /explanation/foo/ do not need to count ../ segments at all, and the output is correct everywhere.

Link patterns by source file location:

Three patterns that look right but are wrong, in every content file:

• ](../explanation/bar/) from a tutorial — resolves to /tutorials/explanation/bar/, not /explanation/bar/. Cross-quadrant links from content files need two ../, or an absolute path.
• ](bar/) with no ../ — resolves inside the current page's URL (/tutorials/foo/bar/). Same-quadrant siblings always need ../.
• ](../tutorials/bar/) from a tutorial — resolves to /tutorials/tutorials/bar/. Same-quadrant links must not repeat the quadrant name; use ../bar/.

The check-link-form deterministic check catches these two patterns (](../<same-quadrant>/…) and ](../<other-quadrant>/…) inside content files) before build. If a subagent generates links and you are about to score or build, run nu checks/run-checks.nu <diataxis_dir> first — link-form failures name file and line so they are cheap to fix.

Hugo frontmatter: Every generated markdown file starts with a TOML frontmatter block (+++ delimiters) containing at least title, weight, and description, plus topic, covers, and detail as page params derived from the matching diataxis.toml entry. Do not repeat the title as an # H1 heading in the body — the Hugo theme renders the title from frontmatter, and a body H1 produces a duplicate. Compute weight as topic.order * 10 + quadrant_weight, where quadrant_weight is 1 for explanation, 2 for tutorials, 3 for howto, 4 for reference. This matches the presentation order (Explanation → Tutorials → How-to → Reference) and groups content by topic within each section. Example frontmatter for the first tutorial in the first topic:

+++
title = "Your First Project"
weight = 12
description = "First steps with the Widget library"
topic = "getting-started"
covers = ["Installing the library", "Creating a first widget"]
detail = "Step-by-step with code examples."
+++

Homepage frontmatter: diataxis/index.md gets title, description, and a [cascade] table setting type = "docs" so every child page inherits the theme's docs layout (relevant to Hextra and similar themes).

Quadrant landing pages: Each of the four quadrant directories gets an _index.md that acts as the section landing page. These pages enforce the presentation order and give readers an orientation before they drill into a specific file. Create one per quadrant with this exact shape:

• Frontmatter with title, description, and a fixed weight that pins the section order: explanation = 10, tutorials = 20, howto = 30, reference = 40, plus examples = 50 on projects that have marimo exercises (see "Exercises landing page" below). These weights match the presentation order the skill requires; the reviewer fails if any are missing or out of order.
• A short introductory paragraph (2-4 sentences) explaining what this quadrant is and when a reader should consult it. Write this for a reader who has landed on the section page and is deciding whether to stay.
• A bulleted list of links to every content file in that quadrant, each with a one-line description of what the page covers. Use the Hugo pretty-URL directory form (filename/), not filename.md. Order the list by the content file's weight so the landing page mirrors the in-section ordering.

Example for the explanation quadrant:

+++
title = "Explanation"
weight = 10
description = "Background, context, and deeper understanding."
+++
Explanation documents discuss the why — the reasoning, design rationale,
and trade-offs behind the project. Read these to deepen understanding,
not to accomplish a task.

- [The Diataxis Framework](diataxis-framework/) — what Diataxis is, the
  two axes that produce the four quadrants, and why the boundaries
  improve documentation quality.
- [Why Structure First](why-structure-first/) — why `diataxis.toml` is
  updated before any content change, and how the `guidance` field
  prevents revision regressions.

When a content file is added, removed, or renamed, update the corresponding quadrant _index.md in the same change so the link list does not drift.

Exercises landing page: When the project has any marimo notebooks under exercises/, author examples/_index.md so the fifth top-level section appears in the nav. Skip this file entirely when no exercises exist — adding it to an exerciseless project creates a phantom section that disappoints the reader who clicks into it. Shape:

• Frontmatter with title = "Exercises", weight = 50, and a description explaining the section in one line. No type override — the landing page is a normal content page, not a leaf bundle.
• A short introductory paragraph (2-4 sentences) framing what the section is: an index of interactive notebooks the reader can run in their browser. Make clear that each link opens a standalone WASM page and that the full tutorial context lives in the matching tutorial.
• One bulleted list per topic, with a topic heading (### <Topic Title>) preceding each list. Within a topic, order exercises by the tutorial's weight, then by file name. Each list item is - [<tutorial title>](/exercises/<stem>/) — <one-line description>. Draw the description from the tutorial's description field in diataxis.toml, narrowed to what the reader will actually do in the notebook (not what the tutorial as a whole teaches).
• Absolute URLs (/exercises/<stem>/) because the source file lives at examples/_index.md and the relative form would be brittle.

Example skeleton, for a project whose exercises cover two topics:

+++
title = "Exercises"
weight = 50
description = "Interactive notebooks you can run in your browser."
+++
Every notebook below is a self-contained Pyodide bundle — no install,
no server. Click through to play with the concept; the matching
tutorial explains what it teaches and when to reach for it.

### Getting Started

- [Build Your First Project](/exercises/build-your-first-project/) —
  scaffold a `diataxis.toml` interactively and watch the structure
  update as you edit.

### Authoring Content

- [Drafting Quadrant Files](/exercises/drafting-quadrant-files/) —
  classify sample paragraphs and see immediate feedback on quadrant
  fit.

Regenerate this file whenever an exercises list anywhere in diataxis.toml is added, removed, or renamed. The landing page is the project-wide view — a change in one topic's exercises still requires refreshing it.

Exercises linking: When a diataxis.toml entry lists exercises, append an ## Exercises section at the end of the generated markdown with links to each exercise's standalone page (/exercises/<stem>/). The exercise stem is the file name without the .py extension. These bundles are produced by make exercises and served as standalone pages with their own look and feel. Both authoring paths are deliberate: inline links keep the exercise adjacent to the tutorial that sets it up, while the Exercises landing page (above) gives readers a project-wide index that does not require picking the right tutorial first.

Math notation: All mathematical expressions must use LaTeX notation. Use \(...\) for inline math and \[...\] for display math. These are LaTeX's canonical delimiters and do not collide with literal dollar signs in prose. The Hugo theme renders them at build time (KaTeX in the default Hextra theme).

The TeX-derived $...$ / $$...$$ form that most other static-site generators use (and that an earlier version of this skill accepted) is also rendered by KaTeX, but the skill canonicalizes on the backslash form for authoring. When upgrade_to_hugo.py runs on a project imported from the old pipeline or from Jekyll, MkDocs, Docusaurus, etc., it rewrites dollar-delimited math to the backslash form; new content should be written that way from the start.

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 Hugo theme renders them client-side at view time.

Exercises: For tutorials in learning-path projects, create marimo .py notebooks under diataxis/exercises/. Every exercise listed in a tutorial's exercises = [...] entry in diataxis.toml must exist as a real, interactive notebook — placeholder stubs (one cell, # TODO bodies, bare pass) are not acceptable. If a tutorial lists an exercise, authoring the notebook is part of that tutorial's generation task, not a follow-up. A subagent generating tutorials/foo.md with exercises = ["exercises/foo-practice.py"] must produce both files before the task is done.

Read references/exercises.md for the shape of a real exercise — at minimum, a setup cell plus a UI cell plus a response cell that reads the UI's value and renders something based on it. That reference also catalogs the marimo mo.ui.* API drift gotchas the skill has been bitten by (e.g. slider uses stop=, not end=; dict-options widgets return the mapped value from .value, not the key) and explains the cell-private underscore-prefix rule. Before using any mo.ui.* widget that is not already demonstrated by the template, fetch the current signature from https://docs.marimo.io/api/ — marimo is pre-1.0 and trains drift across minor versions, so an older remembered signature is a likely source of silent browser-time failures.

Six deterministic checks cover exercises, and all run on every score pass:

• check-exercise-exists — the listed .py file is on disk.
• check-exercise-content — more than one cell, no # TODO/pass stubs.
• check-marimo-ast — the notebook parses as valid Python.
• check-marimo-cell-collisions — no non-underscore name is assigned at the top level of more than one @app.cell (collisions pass export but break in the browser).
• check-marimo-cell-display — no @app.cell ends with a compound control-flow statement (if/for/while/with/try/match). Marimo's compiler only displays the last top-level Expr, so a cell that ends with if cond: mo.md(…) else: mo.md(…) renders as None.
• check-marimo-value-compare — .value == <literal> comparisons on dict-options widgets are tested against the mapped value, not the key (the reverse silently evaluates to False).

All six have a deterministic remediation: write the exercise correctly per references/exercises.md. Treat a failure as a fix to make, not a decision to surface to the user.

The Makefile exports each notebook to a self-contained WASM HTML bundle (via marimo export html-wasm) at diataxis/static/exercises/<stem>/ that runs in the browser via Pyodide — no marimo server is required to view the published output. Every imported package must be Pyodide-compatible; when in doubt, stick to the standard library.

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: hugo (via make build)
• 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 scoring:

nu checks/run-checks.nu <diataxis_dir>

This outputs JSON with pass/fail/skip/error results for structural, format, quadrant rule, and cross-linking checks. If any checks fail, present the failures and their suggestions to the user and wait for direction before proceeding to Phase 2. The user may ask you to fix issues, or they may say "score anyway." Do not proceed to qualitative scoring silently when checks fail.

Exercise-check failures are a deterministic remediation, not a user decision. When check-exercise-exists or check-exercise-content fail, the cause is that the skill's generation step listed an exercise in diataxis.toml but did not produce the corresponding marimo file (or produced a placeholder stub). The fix is the same as writing the exercise in the first place: read the tutorial's covers, detail, and guidance, then author a real interactive notebook per references/exercises.md. Do this in the scoring follow-up rather than presenting it as a choice — the user asked for a score; giving them a list of missing exercises they need to approve generating is making them do the skill's job. Generate the missing notebooks, then re-run the checks, then proceed with scoring. If an entry in the exercises list is outdated and the user no longer wants an exercise there, they will tell you — treat that as feedback and update diataxis.toml.

Phase 2: Qualitative scoring. Once deterministic checks pass (or the user explicitly says to continue), evaluate the documentation qualitatively.

Read references/scoring.md for the full scoring rubric and output format.

Scoring mindset: You are the same model that generated this content. That makes you a biased grader — you will read your own prose as clearer and tighter than it actually is. Counteract this by adopting the stance of a skeptical editor, not a supportive colleague. Assume every paragraph has fat to trim. A paragraph that "works fine" is a 3, not a 4. Reserve high scores for prose you cannot improve. When in doubt, score lower and explain what would earn a higher score — that gives the user actionable direction.

Scoring operates at four levels:

Project level: Is the topic decomposition sound? Are the four quadrants represented appropriately? Are there gaps or redundancies?

Structural level: Does each file match what diataxis.toml says it should contain? Coverage completeness, detail level, guidance adherence.

Quadrant level: Does each file follow the rules for its quadrant type? Cross-contamination detection (tutorial that explains, reference that instructs).

Prose quality: Is the writing tight, direct, and active? Check every file for fluff, passive voice, vague claims, and sentences that can be cut without losing meaning. See the Prose Quality Scoring section in references/scoring.md for the full criteria and calibration examples.

The scoring output is a structured TOML file (scores.toml). Each pass appends a new timestamped [[runs]] entry so the user can see whether changes improved or degraded the documentation over time. Previous entries are read-only historical records used only for the diff after a fresh pass has been produced — they are never a source to read scores from, and you must not populate a new entry by copying values from an earlier one.

Step 5: Revise

Based on scores and user feedback, revise the documentation:

1. Update diataxis.toml if the structure needs to change
2. Regenerate or edit affected files
3. Re-score to verify improvement

The revision cycle is: structure first, content second, score third. Always update the structure document before touching content files. Always score after making changes.

When the user gives feedback like "add more exercises about X" or "this is too hard, add introductory material":

1. Identify where in the topic hierarchy the change belongs
2. Update diataxis.toml with new or modified entries
3. Generate the new content
4. Re-score the affected sections and the project as a whole

Step 6: Build

The skill does not build the site — Hugo does. The diataxis/ directory is a plain Hugo site: the scaffolded hugo.toml mounts each quadrant into Hugo's content tree, diataxis.toml is exposed as a data file, and marimo WASM bundles live under static/exercises/. Presentation is theme-driven, not skill-driven: the default theme is Hextra, and users swap it by editing hugo.toml.

Read references/build-pipeline.md for the technical details.

Users run the build with make, which preprocesses marimo notebooks and then invokes hugo:

cd diataxis
make build           # export exercises + hugo
make serve           # export exercises + hugo server (live reload)
make exercises       # export exercises only
make clean           # remove public/ and resources/

The Makefile exists because Hugo cannot export marimo notebooks on its own; that is the only preprocessing step. Everything else — markdown rendering, navigation, styling, math, mermaid, search — is Hugo's job (or the theme's).

The authored markdown files already carry Hugo frontmatter (written during Step 3), so hugo can build the site directly. No staging step, no custom CLI. A user who prefers not to use make can run hugo directly inside diataxis/ after ensuring exercises are exported.

Marimo notebooks are standalone pages at /exercises/<stem>/. They bypass Hugo's theme entirely and keep their own look and feel. Parent tutorials/howtos link to them via the ## Exercises section appended during content generation.

Content uses generic semantic HTML5 only — no skill-specific CSS classes. Any Hugo theme renders the content correctly.

Deploying: the deployable site is diataxis/public/. Deploy it using any Hugo workflow (hugo deploy, Netlify, GitHub Pages, rsync, etc.).

Directory Layout

A Diataxis project looks like this:

project-root/
├── README.md
├── src/                           # Project source code, etc.
└── diataxis/                      # All Diataxis content lives here
    ├── diataxis.toml              # Source of truth (editorial)
    ├── hugo.toml                  # Hugo config (user-owned after scaffold)
    ├── go.mod                     # Hugo module manifest (user-owned)
    ├── Makefile                   # `make build`, `make serve` (user-owned)
    ├── README.md                  # Guard file ("this is generated output")
    ├── index.md                   # Homepage (signpost)
    ├── scores.toml                # Scoring history
    ├── tutorials/
    │   └── basic-operations.md    # authored markdown with Hugo frontmatter
    ├── howto/
    │   └── add-fractions.md
    ├── reference/
    │   └── fraction-operations.md
    ├── explanation/
    │   └── why-fractions-work.md
    ├── examples/                  # Hugo section dir for the Exercises nav entry;
    │   │                          # optional — appears only if exercises exist
    │   └── _index.md              # Landing page indexing all marimo notebooks
    ├── exercises/
    │   └── basic-ops.py           # marimo notebook
    ├── static/exercises/          # WASM bundles (generated by `make exercises`)
    └── public/                    # Hugo output — the rendered site

The diataxis/ directory is a plain Hugo site plus diataxis.toml as the editorial source of truth. All paths in diataxis.toml are relative to the diataxis/ directory. hugo.toml, go.mod, Makefile, and layouts/ (if added) are user-owned. Everything else under diataxis/ is skill-generated or Hugo-generated output.

Reference Files

These files contain detailed specifications. Read them when you need the details:

• references/quadrants.md — Rules for each Diataxis quadrant (generation + scoring)
• references/structure-schema.md — Full diataxis.toml schema with all fields
• references/scoring.md — Scoring rubric, output format, and comparison logic
• references/build-pipeline.md — Build and serve pipeline technical details
• references/link-resolution.md — Why cross-quadrant links need two ../ (or absolute), with the per-source-location table
• references/exercises.md — What a real marimo exercise looks like (template + guidance), for generation and for remediation when check-exercise-content fails
• references/hugo-migration.md — Detecting pre-Hugo projects and what the upgrade script does
• scripts/upgrade_to_hugo.py — Detect (--check) and migrate pre-Hugo projects to the current Hugo format
• checks/run-checks.nu — Deterministic check runner (invoke with nu checks/run-checks.nu <dir>)
• checks/check-schema.json — JSON Schema for individual check output