From dde771bc1626fae328897b7b8c65c44ee0b361e0 Mon Sep 17 00:00:00 2001 From: Hugh Perkins Date: Wed, 24 Jun 2026 09:24:49 -0700 Subject: [PATCH 1/4] [CI] Fold reading-order (no-forward-reference) check into doc-quality Add RULE 3 to the doc-quality agent prompt: within a single doc, information must be ordered so a first-time reader can follow it top-to-bottom without jumping ahead (no forward references). Includes carve-outs for roadmaps, optional "see below" pointers, backward references, cross-doc references, and conventional preamble ordering, and hands pure undefined-term cases to Rule 1. Adds the [order] tag and reworks the violation cap so one rule cannot crowd out the others. --- .github/workflows/check_doc_quality.yml | 34 ++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/.github/workflows/check_doc_quality.yml b/.github/workflows/check_doc_quality.yml index 5e163d8b52..7bd82eae70 100644 --- a/.github/workflows/check_doc_quality.yml +++ b/.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.). @@ -118,16 +118,42 @@ jobs: VIOLATION: internal / non-end-user material (subject to the carve-outs above) appears outside of such a clearly-marked advanced / under-the-hood 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
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). + A plain term that is simply never defined belongs to Rule 1, not here; Rule 3 covers + ordering dependencies (concepts, examples, parameters, results) where the explanation DOES + exist in the file but appears too late. Do not double-flag the same issue under both rules. + 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 - file independently. Stop after finding 10 violations in total. + file independently against all three rules. Stop after reporting 10 violations in total, + but do not let one rule crowd out the others: if more than one rule has violations, make + sure each such rule is represented in your list before you stop. 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: - : [term|scope]: - where [term] is a Rule 1 violation and [scope] is a Rule 2 violation. + : [term|scope|order]: + 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) From aafcc41c71b4703d0d0e9d8a1a267e1d887e4bd1 Mon Sep 17 00:00:00 2001 From: Hugh Perkins Date: Wed, 24 Jun 2026 09:25:17 -0700 Subject: [PATCH 2/4] [Doc] Document reading-order rule in doc-quality check description The doc-quality check now enforces a third rule (reading order / no forward references); describe it and its carve-outs in contributing.md. --- docs/source/user_guide/contributing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/user_guide/contributing.md b/docs/source/user_guide/contributing.md index bc7231fda0..f7826be26c 100644 --- a/docs/source/user_guide/contributing.md +++ b/docs/source/user_guide/contributing.md @@ -180,9 +180,9 @@ The agent reports up to 5 violations, each annotated with the host file's hotnes ### Doc quality check (`check_doc_quality.yml`) -Uses an AI agent to review documentation changes for an end-user audience (someone writing Quadrants kernels in Python, not a compiler engineer). For each `docs/**/*.md` file added or modified in the PR, it reads the entire current file (not just the diff) and checks two 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; (2) **end-user relevance** — internal / implementation / contributor-only material must be confined to a clearly-marked section whose heading contains "Advanced", "Under the hood", "Internals", or "Implementation". +Uses an AI agent to review documentation changes for an end-user audience (someone writing Quadrants kernels in Python, not a compiler engineer). For each `docs/**/*.md` file added or modified in the PR, it 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; (2) **end-user relevance** — internal / implementation / contributor-only material must be confined to a clearly-marked section whose heading contains "Advanced", "Under the hood", "Internals", or "Implementation"; (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 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. +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. ### PR change report (`pr_change_report.yml`) From 899600ef3501bf4cbb9bc2090b1c67d597a8e2e6 Mon Sep 17 00:00:00 2001 From: Hugh Perkins Date: Wed, 24 Jun 2026 09:27:39 -0700 Subject: [PATCH 3/4] [CI] Simplify doc-quality RULE 3: drop reworked cap and double-flag note Both added cognitive load to the agent for little gain. Revert to the original "stop after 10 violations" cap and remove the Rule 1/Rule 3 delineation note. --- .github/workflows/check_doc_quality.yml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/workflows/check_doc_quality.yml b/.github/workflows/check_doc_quality.yml index 7bd82eae70..4fbb9f8aed 100644 --- a/.github/workflows/check_doc_quality.yml +++ b/.github/workflows/check_doc_quality.yml @@ -134,18 +134,13 @@ jobs: - 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). - A plain term that is simply never defined belongs to Rule 1, not here; Rule 3 covers - ordering dependencies (concepts, examples, parameters, results) where the explanation DOES - exist in the file but appears too late. Do not double-flag the same issue under both rules. 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 - file independently against all three rules. Stop after reporting 10 violations in total, - but do not let one rule crowd out the others: if more than one rule has violations, make - sure each such rule is represented in your list before you stop. + file independently. Stop after finding 10 violations in total. 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 From 1e4e9f4a05e281ba3bef5c36ac34334e489edb3a Mon Sep 17 00:00:00 2001 From: Hugh Perkins Date: Fri, 26 Jun 2026 13:51:27 -0400 Subject: [PATCH 4/4] add ref to scikit-build-core --- docs/source/user_guide/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/user_guide/contributing.md b/docs/source/user_guide/contributing.md index f7826be26c..83ed115510 100644 --- a/docs/source/user_guide/contributing.md +++ b/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):