[CI] Add doc sequence check to doc quality check

.github/workflows/check_doc_quality.yml

@@ -61,7 +61,7 @@ jobs:
           /tmp/changed_docs.txt contains a newline-separated list of Markdown (.md) doc files (paths
           relative to the repo root) that were added or modified in this PR. For EACH file in that
           list, read the FULL current contents of the file (not just the diff) and review it against
-          the two rules below.
+          the three rules below.
 
           Target audience: an *end user* of Quadrants. That is, someone who writes GPU programs in
           Python using the Quadrants library (`@qd.kernel`, `@qd.func`, ndarrays, fields, etc.).
@@ -125,6 +125,25 @@ jobs:
           VIOLATION: internal / non-end-user material (subject to the carve-outs above) appears
           outside of an advanced / internal section.
 
+          RULE 3 — Reading order (no forward references).
+          Within a single doc, information should be ordered so a first-time reader can follow it
+          top-to-bottom in one pass, without jumping ahead. A FORWARD REFERENCE is when a passage
+          depends on a concept, parameter, behavior, code element, or result that is only introduced
+          LATER in the SAME file, such that the reader cannot understand the current passage without
+          first reading the later one.
+          The following are NOT order violations:
+          - A brief overview / roadmap near the top that previews upcoming sections ("this guide
+            covers A, then B") — signposting the structure, not a dependency: the reader does not
+            need to understand A or B yet to keep reading.
+          - Optional "for more detail, see <section> below" pointers, where the current passage is
+            fully understandable WITHOUT following them. The test is: MUST read ahead to understand
+            (violation) vs more depth merely available later (fine).
+          - Backward references (to something earlier in the same file) are always fine.
+          - References to OTHER docs/files; this rule is about ordering WITHIN a single file only.
+          - Conventional preamble ordering (e.g. Prerequisites -> Installation -> Usage).
+          VIOLATION: a passage cannot be understood by a first-time reader at the point they reach
+          it, because what it relies on is only introduced later in the same file.
+
           Read each listed file in full before judging it. You may open any other file in the repo
           (e.g. linked docs) to verify whether a term is defined elsewhere. Do NOT modify any files.
           Be precise and conservative: only flag clear violations, not borderline cases. Judge each
@@ -133,8 +152,10 @@ jobs:
           If there are NO violations, your final output must start with the word PASS.
           If there ARE violations, your final output must start with the word FAIL, followed by a list
           of violations (up to 10), one per line, in the format:
-          <filepath>: [term|scope]: <brief description>
-          where [term] is a Rule 1 violation and [scope] is a Rule 2 violation.
+          <filepath>: [term|scope|order]: <brief description>
+          where [term] is a Rule 1 violation, [scope] is a Rule 2 violation, and [order] is a Rule 3
+          violation (for [order], cite both line numbers — what is used at line N is only introduced
+          at line M).
           PROMPT
           )" --model claude-4.6-opus-high-thinking --mode ask --output-format text --trust)
 

docs/source/user_guide/contributing.md

@@ -54,7 +54,7 @@ uv pip install --group dev --group test
 
 `build.py` can be used at least two ways:
 
-* `build.py wheel` to build the wheel (via scikit-build-core, i.e. `pip wheel`)
+* `build.py wheel` to build the wheel (via [scikit-build-core](https://scikit-build-core.readthedocs.io/en/latest/), i.e. `pip wheel`)
 * `build.py --shell` to enter a shell with environment variables set up as with `build.py wheel` in order to let you invoke yourself the commands.
 
 For incremental development, do an editable install (scikit-build-core "redirect" mode: the compiled core is installed and rebuilt on demand, Python edits are live):
@@ -186,11 +186,12 @@ Uses an AI agent to review documentation changes for an end-user audience (someo
 Let's first define an *advanced / internal section* as a clearly-marked section whose heading contains "Advanced", "Under the hood", "Internals", or "Implementation"; it targets a more advanced reader rather than the typical end user.
 
 
-For each `docs/**/*.md` file added or modified in the PR, the CI agent reads the entire current file (not just the diff) and checks two things:
+For each `docs/**/*.md` file added or modified in the PR, the CI agent reads the entire current file (not just the diff) and checks three things:
 - (1) **undefined terms** — a term a typical user is unlikely to know (specialized or internal jargon, project-specific abbreviations) must be defined at its first use in that file, either inline or via a link to a doc that defines it, unless that first use is inside an advanced / internal section;
-- (2) **end-user relevance** — internal / implementation / contributor-only material must be confined to an advanced / internal section.
+- (2) **end-user relevance** — internal / implementation / contributor-only material must be confined to an advanced / internal section;
+- (3) **reading order** — information must be ordered so a first-time reader can follow the file top-to-bottom in one pass, without forward references (a passage that can only be understood by reading something introduced later in the same file).
 
-The following do not count as violations: references to public APIs that the author links to their docs and/or labels as public; brief reader-directed pointers suggesting the reader could contribute upstream or file an issue; the core public API vocabulary a user already knows (e.g. `@qd.kernel`, `@qd.func`, `qd.Template`, fields, ndarrays).
+The following do not count as violations: references to public APIs that the author links to their docs and/or labels as public; brief reader-directed pointers suggesting the reader could contribute upstream or file an issue; the core public API vocabulary a user already knows (e.g. `@qd.kernel`, `@qd.func`, `qd.Template`, fields, ndarrays); and, for the reading-order check, an overview/roadmap near the top, optional "see below" pointers (where the current passage still reads fine on its own), and backward references.
 
 The agent reports up to 10 violations. This check is delayed by 30 minutes, to avoid running repeatedly if multiple commits pushed with a short delay between each.