diff --git a/papers/QUALITY-RUBRIC.md b/papers/QUALITY-RUBRIC.md new file mode 100644 index 0000000000..0accfd0a42 --- /dev/null +++ b/papers/QUALITY-RUBRIC.md @@ -0,0 +1,180 @@ +# The Quality Rubric for AC Papers + +What a finished paper on **papers.aesthetic.computer** has to clear before it +counts as done. This is the companion to `VOICE.md` (how a paper *sounds*) and +`HAND.md` (how code *reads*) — this file is how a paper is *built and checked*. +It was reverse-engineered from the publishing stack itself: `cli.mjs`, +`tools/check-columns.mjs`, the three `.sty` files, `bin/gen-cover.mjs`, and the +figure-rich exemplar `arxiv-keymaps/keymaps.tex`. When the tooling and this doc +disagree, the tooling wins — fix this file. + +The exemplar to hold a flagship paper against is **`arxiv-keymaps`**. When in +doubt, open it. + +Two of these gates are enforced by tools today; everything else is enforced by +reading the paper next to keymaps. The two hard gates are flagged **[HARD]**. + +--- + +## A — Voice & argument (`VOICE.md`) + +- **A1** First person, plain. "i built this," not "the author implemented." Grep + the `.tex` for `we propose`, `the authors`, `it should be noted`, `a novel + approach to`, `in this paper we` → zero hits. +- **A2** Conviction, quiet but absolute. The conclusion states a belief plainly. + No "results suggest potential viability." +- **A3** Em dashes for asides, short sentences, fragments that land. `---`, not + semicolon or parenthesis chains. +- **A4** Cite when it matters, never to prove you read things. No paragraph is a + bare pile of `\citep{}`. +- **A5** The register gradient holds: abstract formal-ish but ends on a line that + lands; intro opens on the *thing*, not a lit survey; body is whiteboard-precise; + limitations say what's broken before anyone asks; conclusion is yours. +- **A6** One source file for cards + arxiv. Never maintain divergent content + across formats. + +## B — Structure + +- **B1** Abstract in a `\begin{quote}…\textbf{Abstract.}` block after the title. + One dense paragraph, lands on its last line. +- **B2** Introduction names the object first — often "Figure 1 is…" — and ends + with a one-line roadmap of the movements to come. +- **B3** Numbered body sections carry `\label{sec:…}` and cross-reference each + other by label. +- **B4** A limitations pass, or an honest counter-case, that argues against the + paper's own favored object at least once — without minimizing or dramatizing. +- **B5** Conclusion restates the contribution and the belief. +- **B6** `\section*{Acknowledgments}` when there's a residency or venue context, + with the pals badge. + +## C — Citations + +- **C1** natbib + `plainnat`. Every `.bib` entry is actually `\cite`d; every + `\cite` resolves. Build shows no "undefined citation." +- **C2** Load-bearing citations are real and read — the theoretical anchor is + cited repeatedly, not name-dropped once. +- **C3** **Diversity is a quality axis, not an afterthought.** The house target + from the `arxiv-diversity` audit: **≥30% women authors, ≥20% non-Western + authors.** A cluster of citations that is all-male or all-Western is a defect to + fix before publishing, the same as a broken build. Verify each new citation's + metadata against a primary source — guessed page numbers and years are how + wrong citations ship. +- **C4** Prefer the platter reading corpus (`system/public/assets/papers/ + readings/`) as the scholarly foundation where it fits. + +## D — Figures (the keymaps standard) + +Keymaps carries 7 figures (2 full-width `figure*`), 2 tables, and 28 QR tiles. A +flagship paper is expected to show its argument, not just state it. + +- **D1** Real figures built from the argument — hand-built TikZ diagrams, or + captured screenshots of the actual thing under discussion (a UI, a piece, a + real user comment) — not decorative filler. +- **D2** Wide content spans both columns via `figure*[t]` / `table*[p]`. +- **D3** Captions are dense and explanatory. A caption says what to read *and* + what it proves. "Figure 1: the system" fails. +- **D4** Where the paper catalogs external objects, each resolves to a canonical + home via a `\qrc{}` QR tile. +- **D5** Inline micro-glyphs (`\key{}`, keycap chips, etc.) used consistently when + they aid reading. +- **D6** Screenshots are legitimate evidence: the coarse UI being criticized, the + AC piece being praised, the user comment proving demand. Caption them like + exhibits — say what the reader is looking at and why it is in the paper. + +## E — Cover (`bin/gen-cover.mjs`) + +- **E1** A hand-rendered **emblem on cream paper** (colored pencil + gouache, + silkscreen imperfection) generated by `gen-cover.mjs` (OpenAI gpt-image-2). + Reads like a record-label seal or a band-tee print. +- **E2** ONE singular subject, floating in the central two-thirds, periphery + dissolving to bare paper. No frame, no border, no background scene, no clusters. +- **E3** Never spell the subject's name. Identity is carried by emblem, + silhouette, color, era. +- **E4** Muted natural palette, square 1:1. +- **E5** Prompt lives at `figures/cover-prompt.txt`; output `figures/cover.png`. +- **E6** Included in the title block at `width=0.5–0.7\textwidth`, centered. +- **E7** The cover feeds the index tile (`genCoverTile`); a paper with a + `figures/cover.png` gets a designed tile instead of a page-1 render. + +## F — Typography & layout + +- **F1** `\documentclass[10pt,letterpaper,twocolumn]{article}`, `% !TEX program = + xelatex`. (Essays use `ac-paper-essay.sty`; cards use `ac-paper-cards.sty`.) +- **F2** Geometry `0.75in` margins, folio clear of the sheet edge. +- **F3** Body is **Latin Modern** (Roman/Sans/Mono, mono `Scale=0.85`). **YWFT + Processing** (`\acbold`/`\aclight`) is reserved for the title and header only — + its punctuation glyphs are unreliable in body text. +- **F4** AC palette exact: `acpink 180,72,135` · `acpurple 120,80,180` · + `acdark 64,56,74` · `acgray 119,119,119`. Diagram chips (`acgreen`/etc.) allowed. +- **F5** `\section` = bold, normalsize, UPPERCASE, `\thesection.`, tight spacing. +- **F6** hyperref links colored `acpurple`; `xurl` loaded; `pdftitle`/`pdfauthor` + set. +- **F7** Long identifiers/paths wrap via a `\code{}`-style command so they never + overflow. Two-column breaking tuned (`\tolerance`, `\emergencystretch`, + `\hyphenpenalty`). Use `\raggedbottom` so short paragraphs don't get their + inter-paragraph glue stretched into false "title" spacing. +- **F8 [HARD]** **Nothing may break the columnar arrangement.** + `node papers/cli.mjs check` reports zero `Overfull \hbox > 0.5pt`. This is the + rule: nothing ships that breaks the columns. +- **F9** Title block: `\acbold` title in `acdark`, cover, italic subtitle in + `acpink`, byline `@jeffrey · Aesthetic.Computer · ORCID 0009-0007-4460-4913`, + language bar, then a pink rule. Every dot in "Aesthetic.Computer" is the pink + `\acdot`. + +## G — Build & publish hygiene (`cli.mjs`) + +- **G1 [HARD]** Build is **xelatex 3-pass + bibtex** (`xelatex; bibtex; xelatex; + xelatex`). Success = a real PDF exists, not exit code. +- **G2 [HARD]** No silent failure: the `.log` contains no `! Package fontspec + Error` and no `nullfont`. A stub PDF from a font fallback is a broken build even + though xelatex exits 0. +- **G3** Deterministic PDFs: `SOURCE_DATE_EPOCH` from newest source mtime. Same + bytes in → same bytes out (this is what keeps the oven from auto-commit loops). +- **G4** Version stamp: `\InputIfFileExists{version}` pulls `\paperhash` (git + short hash, `+` if the paper dir is dirty) and `\paperrev`, with a `dev`/`?` + fallback, rendered in a colophon badge. +- **G5** History stamp: `\InputIfFileExists{history}` renders an in-PDF changelog + from the git log of the paper's own `.tex`. +- **G6** Draft watermark on by default (45° pink "WORKING DRAFT" + the + "Working Draft — not for citation" header). A print edition turns it off. +- **G7** Registered in `PAPER_MAP`: `{ base, siteName, title }`, siteName ending + `-26-arxiv` (or `-essay` / `-deck` / `-dossier-26-arxiv`). +- **G8** In exactly one `CATEGORIES` lane (platform / essays / audits / decks / + dossiers / software). Uncategorized triggers a WARN. +- **G9** Has an `IMPORTANCE` rank (missing → 99, sinks to the bottom of the index). +- **G10** `metadata.json` entry with a real `created` date; `revisions` + increments on each publish. +- **G11** Thumbnail generated in `thumbs/{siteName}.jpg` (cover tile preferred). +- **G12** Index + Atom feed regenerated; `verify` reports zero broken PDF links. +- **G13** `PAPER_COPY` entry with a `detail` line and an `abstract` for the index + card and the feed. +- **G14** Optional lanes if present: cards (`{base}-cards.tex`), translations + (da/es/zh/ja/ru), a `PODCASTS` reading. + +--- + +## The review pass (run this before calling a paper done) + +1. **Voice** — grep the banned phrases (A1); the conclusion states a belief (A2, B5). +2. **Structure** — abstract-quote, object-first intro with roadmap, honest + limitations, conclusion, acknowledgments (B1–B6). +3. **Citations** — every entry cited and resolving; metadata verified against + primary sources; ≥30% women / ≥20% non-Western (C1–C3). +4. **Figures** — real diagrams and captured exhibits with dense captions; wide + ones as `figure*`; QR tiles resolve (D1–D6). +5. **Cover** — single emblem, cream paper, no name, 1:1; included at + 0.5–0.7\textwidth (E1–E6). +6. **Layout** — 10pt twocolumn, Latin Modern body + ywft title, palette exact, + `node papers/cli.mjs check` = 0 overflows (F1–F9). +7. **Build/publish** — xelatex 3-pass+bibtex clean, `.log` free of `fontspec + Error`/`nullfont`, watermark on for drafts, registered in `PAPER_MAP` / + `CATEGORIES` / `IMPORTANCE` / `PAPER_COPY` / `metadata.json`, thumbnail + feed + + no broken links (G1–G13). + +The teeth today are **F8** and **G1–G2** — the column check and a clean, +non-stub xelatex build. Everything else is enforced by holding the paper up next +to keymaps and being honest about the difference. + +--- + +*Maintained alongside `VOICE.md`. Update this when the tooling changes.*