paperlint 4.1.0 → 4.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +24 -0
- package/CONTRIBUTING.md +7 -0
- package/dist/adapters/latex/document-class.d.ts +6 -5
- package/dist/adapters/latex/document-class.d.ts.map +1 -1
- package/dist/adapters/latex/document-class.js +18 -10
- package/dist/adapters/latex/document-class.js.map +1 -1
- package/dist/adapters/latex/includes.d.ts +12 -0
- package/dist/adapters/latex/includes.d.ts.map +1 -0
- package/dist/adapters/latex/includes.js +42 -0
- package/dist/adapters/latex/includes.js.map +1 -0
- package/dist/adapters/latex/index.d.ts +9 -5
- package/dist/adapters/latex/index.d.ts.map +1 -1
- package/dist/adapters/latex/index.js +8 -1
- package/dist/adapters/latex/index.js.map +1 -1
- package/dist/adapters/latex/nodes.d.ts +5 -1
- package/dist/adapters/latex/nodes.d.ts.map +1 -1
- package/dist/adapters/latex/nodes.js +6 -2
- package/dist/adapters/latex/nodes.js.map +1 -1
- package/dist/adapters/latex/parse.d.ts.map +1 -1
- package/dist/adapters/latex/parse.js +1 -0
- package/dist/adapters/latex/parse.js.map +1 -1
- package/dist/adapters/latex/prose.d.ts +8 -0
- package/dist/adapters/latex/prose.d.ts.map +1 -0
- package/dist/adapters/latex/prose.js +353 -0
- package/dist/adapters/latex/prose.js.map +1 -0
- package/dist/claim-provenance.d.ts +34 -0
- package/dist/claim-provenance.d.ts.map +1 -0
- package/dist/claim-provenance.js +146 -0
- package/dist/claim-provenance.js.map +1 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +20 -0
- package/dist/cli.js.map +1 -1
- package/dist/domain/paper-source.d.ts +58 -0
- package/dist/domain/paper-source.d.ts.map +1 -0
- package/dist/domain/paper-source.js +109 -0
- package/dist/domain/paper-source.js.map +1 -0
- package/dist/domain/sentences.d.ts +26 -0
- package/dist/domain/sentences.d.ts.map +1 -0
- package/dist/domain/sentences.js +48 -0
- package/dist/domain/sentences.js.map +1 -0
- package/dist/domain/tex-document.d.ts +39 -4
- package/dist/domain/tex-document.d.ts.map +1 -1
- package/dist/domain/tex-document.js.map +1 -1
- package/dist/eslint-rules/paper-typography.d.ts +7 -0
- package/dist/eslint-rules/paper-typography.d.ts.map +1 -1
- package/dist/eslint-rules/paper-typography.js +53 -1
- package/dist/eslint-rules/paper-typography.js.map +1 -1
- package/dist/ports/latex.d.ts +12 -1
- package/dist/ports/latex.d.ts.map +1 -1
- package/dist/register.d.ts +40 -0
- package/dist/register.d.ts.map +1 -0
- package/dist/register.js +134 -0
- package/dist/register.js.map +1 -0
- package/dist/tex-paper.d.ts +19 -0
- package/dist/tex-paper.d.ts.map +1 -0
- package/dist/tex-paper.js +105 -0
- package/dist/tex-paper.js.map +1 -0
- package/dist/tex-venue-rules.d.ts +7 -2
- package/dist/tex-venue-rules.d.ts.map +1 -1
- package/dist/tex-venue-rules.js +31 -17
- package/dist/tex-venue-rules.js.map +1 -1
- package/docs/rules/tex/claim-provenance.md +83 -0
- package/docs/rules/tex/missing-input.md +58 -0
- package/docs/rules/tex/register.md +77 -0
- package/docs/rules/tex/required-section.md +3 -1
- package/docs/rules/tex/template.md +12 -0
- package/docs/rules/tex/venue-leftover.md +4 -2
- package/docs/rules.md +3 -0
- package/eslint-rules/paper-typography.test.mjs +48 -1
- package/eslint-rules/paper-typography.ts +72 -1
- package/eslint.config.mjs +1 -0
- package/fixtures/real-markdown-paper/baseline.ts +8 -7
- package/package.json +2 -1
- package/skills/cold-read-diff/SKILL.md +31 -10
- package/skills/cold-read-diff/SKILL.md.spec.ts +30 -9
- package/skills/draft-paper/SKILL.md +2 -2
- package/skills/draft-paper/SKILL.md.spec.ts +1 -1
- package/skills/grade-paper-writing/SKILL.md +109 -44
- package/skills/grade-paper-writing/SKILL.md.spec.ts +108 -43
- package/skills/harden-paper/SKILL.md +35 -36
- package/skills/harden-paper/SKILL.md.spec.ts +34 -35
- package/skills/paper-adversarial-review/SKILL.md +2 -2
- package/skills/paper-adversarial-review/SKILL.md.spec.ts +1 -1
- package/skills/paper-pipeline/SKILL.md +3 -3
- package/skills/paper-pipeline/SKILL.md.spec.ts +2 -2
- package/skills/paper-pipeline/grade-paper-writing-ablation.eval.mjs +6 -6
- package/skills/paper-pipeline/references/writing-craft.md +53 -18
- package/skills/pc-panel-review/SKILL.md +36 -11
- package/skills/pc-panel-review/SKILL.md.spec.ts +35 -10
- package/src/adapters/latex/document-class.ts +20 -12
- package/src/adapters/latex/includes.ts +66 -0
- package/src/adapters/latex/index.test.ts +175 -1
- package/src/adapters/latex/index.ts +14 -4
- package/src/adapters/latex/nodes.ts +11 -2
- package/src/adapters/latex/parse.ts +1 -0
- package/src/adapters/latex/prose.ts +484 -0
- package/src/claim-provenance.test.ts +352 -0
- package/src/claim-provenance.ts +217 -0
- package/src/cli.ts +20 -0
- package/src/domain/paper-source.test.ts +156 -0
- package/src/domain/paper-source.ts +233 -0
- package/src/domain/sentences.ts +67 -0
- package/src/domain/tex-document.ts +36 -3
- package/src/ports/latex.ts +13 -0
- package/src/register.test.ts +165 -0
- package/src/register.ts +177 -0
- package/src/rule-cases.test.ts +54 -4
- package/src/tex-paper.test.ts +131 -0
- package/src/tex-paper.ts +152 -0
- package/src/tex-venue-rules.test.ts +87 -5
- package/src/tex-venue-rules.ts +62 -30
- package/skills/harden-paper/fixtures/uncited-assertions-sample.md +0 -43
- package/skills/harden-paper/fixtures/uncited-assertions-sample.tex +0 -77
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: cold-read-diff
|
|
3
|
-
description: Send just-changed paper prose to
|
|
3
|
+
description: Send just-changed paper prose to two readers with NO context — an engineer who asks what each sentence claims, and a skimming workshop reviewer who asks whose result it states and whether it reads like a paper — the only check that catches a sentence which is short, true, jargon-free and still meaningless to anyone who does not already know the idea. Run after every prose edit to a paper, before calling the edit done, and before reporting a section as fixed. Scoped to the diff, so it is cheap enough to run every time. Not a writing grade (grade-paper-writing), not a structural pass (tighten-paper), not a defect review.
|
|
4
4
|
context: fork
|
|
5
5
|
allowed-tools: [Bash, Read, Agent]
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
<!-- vigiles:sha256:
|
|
8
|
+
<!-- vigiles:sha256:293f0627e6873774 compiled from skills/cold-read-diff/SKILL.md.spec.ts -->
|
|
9
9
|
|
|
10
10
|
# cold-read-diff — the reader who cannot fake understanding
|
|
11
11
|
|
|
@@ -57,21 +57,41 @@ one, and its confusion is the finding.
|
|
|
57
57
|
|
|
58
58
|
1. **Take the diff.** `git diff -U0 -- <paper.md>` since the last commit, or the `new_string` of the
|
|
59
59
|
edits just applied. Prose only — skip comments, tables, bibliography.
|
|
60
|
-
2. **Spawn
|
|
61
|
-
prompt**, not as a file path. A path is an invitation to read
|
|
62
|
-
neighbours is how the check fails silently. `sonnet` is the right
|
|
63
|
-
and not the one that wrote the sentence.
|
|
64
|
-
|
|
60
|
+
2. **Spawn TWO agents with no repository context, one per persona, in parallel.** Give each the
|
|
61
|
+
changed paragraphs **as text in the prompt**, not as a file path. A path is an invitation to read
|
|
62
|
+
the neighbours, and reading the neighbours is how the check fails silently. `sonnet` is the right
|
|
63
|
+
model: competent, cheap, and not the one that wrote the sentence.
|
|
64
|
+
|
|
65
|
+
| persona | who | what only it can report |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| **the engineer** | a strong practitioner outside academia, reading closely | a sentence that parses only for a reader who already holds the idea |
|
|
68
|
+
| **the workshop reviewer** | a PC member at the target venue with 40 minutes for the whole paper, skimming the abstract, the introduction and the conclusion, Confidence 3 | a sentence whose result has no owner, a relation between claims left to infer, a sentence that does not read like a paper at this venue |
|
|
69
|
+
|
|
70
|
+
The engineer cannot see the second column: a sentence with no stated owner reads to him as
|
|
71
|
+
confident, and he does not know the venue's register. Both run, every time; neither replaces the
|
|
72
|
+
other. The reviewer is told the venue's name and nothing else. When the diff touches none of the
|
|
73
|
+
abstract, the introduction and the conclusion, the reviewer still reads it — as the paragraph a
|
|
74
|
+
skimming reviewer lands on.
|
|
75
|
+
3. **Ask the engineer exactly two questions per sentence:**
|
|
65
76
|
- *What does this sentence claim? Restate it in your own words.* If restating requires guessing,
|
|
66
77
|
the answer is `CANNOT PARSE` plus what stopped them — an undefined term, a pronoun with no
|
|
67
78
|
referent, a number with no denominator, two clauses that do not connect.
|
|
68
79
|
- *Would a reader who stops here understand it?* Yes / No / Only-if-they-know-X.
|
|
80
|
+
|
|
81
|
+
**Ask the reviewer two different ones:**
|
|
82
|
+
- *Whose result does this sentence state — the authors' measurement, a cited work, or a property
|
|
83
|
+
of the world?* If it cannot tell, the answer is `WHOSE?` with the sentence quoted.
|
|
84
|
+
- *Does this read like a paper at this venue?* If not, `REGISTER` with the sentence quoted and
|
|
85
|
+
what a paper there would write instead — an aphorism, a fragment, a colloquial turn, or two
|
|
86
|
+
claims side by side with the relation between them unstated.
|
|
69
87
|
4. **Ask for the dangerous class explicitly:** *which sentences sound clever but say less than they
|
|
70
88
|
appear to?* Those read fine and carry nothing, and they are the ones a knowing reader waves
|
|
71
89
|
through.
|
|
72
90
|
5. **Apply the fixes — as rewrites of the whole thought, never as excisions.** See the rule below.
|
|
73
|
-
6. **Re-run on the fix.** An edit is not done until the
|
|
74
|
-
|
|
91
|
+
6. **Re-run on the fix, with both personas.** An edit is not done until the engineer parses the
|
|
92
|
+
replacement AND the reviewer finds its owner and its register. A fix for the engineer that goes
|
|
93
|
+
colloquial is a new `REGISTER` finding, and the reverse holds too. One confirming round; do not
|
|
94
|
+
loop past it.
|
|
75
95
|
|
|
76
96
|
## 🔴 Hand the reader WHOLE PARAGRAPHS, never `+` lines
|
|
77
97
|
|
|
@@ -115,7 +135,8 @@ findings:
|
|
|
115
135
|
|
|
116
136
|
- 🔴 **No context in the prompt. Ever.** Not the title, not the abstract, not "this is a paper about
|
|
117
137
|
agent rules files". Every sentence of background handed to the reader is a sentence of confusion
|
|
118
|
-
they will no longer report.
|
|
138
|
+
they will no longer report. The one exception is the venue's name, given to the reviewer persona:
|
|
139
|
+
judging register without knowing the venue is guessing.
|
|
119
140
|
- 🔴 **A fix that removes the flagged construction and keeps the compression is not a fix.** Proven
|
|
120
141
|
twice in one hour: *"not through any defect in how we write it, but because that is what English
|
|
121
142
|
is"* → *"that is what English is for"* (tic gone, meaning inverted into nonsense); *"the agent
|
|
@@ -8,7 +8,7 @@ import { experimental_skill } from "vigiles/spec";
|
|
|
8
8
|
export default experimental_skill({
|
|
9
9
|
name: "cold-read-diff",
|
|
10
10
|
description:
|
|
11
|
-
"Send just-changed paper prose to
|
|
11
|
+
"Send just-changed paper prose to two readers with NO context — an engineer who asks what each sentence claims, and a skimming workshop reviewer who asks whose result it states and whether it reads like a paper — the only check that catches a sentence which is short, true, jargon-free and still meaningless to anyone who does not already know the idea. Run after every prose edit to a paper, before calling the edit done, and before reporting a section as fixed. Scoped to the diff, so it is cheap enough to run every time. Not a writing grade (grade-paper-writing), not a structural pass (tighten-paper), not a defect review.",
|
|
12
12
|
context: "fork",
|
|
13
13
|
tools: ["Bash", "Read", "Agent"],
|
|
14
14
|
body: `
|
|
@@ -62,21 +62,41 @@ one, and its confusion is the finding.
|
|
|
62
62
|
|
|
63
63
|
1. **Take the diff.** \`git diff -U0 -- <paper.md>\` since the last commit, or the \`new_string\` of the
|
|
64
64
|
edits just applied. Prose only — skip comments, tables, bibliography.
|
|
65
|
-
2. **Spawn
|
|
66
|
-
prompt**, not as a file path. A path is an invitation to read
|
|
67
|
-
neighbours is how the check fails silently. \`sonnet\` is the right
|
|
68
|
-
and not the one that wrote the sentence.
|
|
69
|
-
|
|
65
|
+
2. **Spawn TWO agents with no repository context, one per persona, in parallel.** Give each the
|
|
66
|
+
changed paragraphs **as text in the prompt**, not as a file path. A path is an invitation to read
|
|
67
|
+
the neighbours, and reading the neighbours is how the check fails silently. \`sonnet\` is the right
|
|
68
|
+
model: competent, cheap, and not the one that wrote the sentence.
|
|
69
|
+
|
|
70
|
+
| persona | who | what only it can report |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| **the engineer** | a strong practitioner outside academia, reading closely | a sentence that parses only for a reader who already holds the idea |
|
|
73
|
+
| **the workshop reviewer** | a PC member at the target venue with 40 minutes for the whole paper, skimming the abstract, the introduction and the conclusion, Confidence 3 | a sentence whose result has no owner, a relation between claims left to infer, a sentence that does not read like a paper at this venue |
|
|
74
|
+
|
|
75
|
+
The engineer cannot see the second column: a sentence with no stated owner reads to him as
|
|
76
|
+
confident, and he does not know the venue's register. Both run, every time; neither replaces the
|
|
77
|
+
other. The reviewer is told the venue's name and nothing else. When the diff touches none of the
|
|
78
|
+
abstract, the introduction and the conclusion, the reviewer still reads it — as the paragraph a
|
|
79
|
+
skimming reviewer lands on.
|
|
80
|
+
3. **Ask the engineer exactly two questions per sentence:**
|
|
70
81
|
- *What does this sentence claim? Restate it in your own words.* If restating requires guessing,
|
|
71
82
|
the answer is \`CANNOT PARSE\` plus what stopped them — an undefined term, a pronoun with no
|
|
72
83
|
referent, a number with no denominator, two clauses that do not connect.
|
|
73
84
|
- *Would a reader who stops here understand it?* Yes / No / Only-if-they-know-X.
|
|
85
|
+
|
|
86
|
+
**Ask the reviewer two different ones:**
|
|
87
|
+
- *Whose result does this sentence state — the authors' measurement, a cited work, or a property
|
|
88
|
+
of the world?* If it cannot tell, the answer is \`WHOSE?\` with the sentence quoted.
|
|
89
|
+
- *Does this read like a paper at this venue?* If not, \`REGISTER\` with the sentence quoted and
|
|
90
|
+
what a paper there would write instead — an aphorism, a fragment, a colloquial turn, or two
|
|
91
|
+
claims side by side with the relation between them unstated.
|
|
74
92
|
4. **Ask for the dangerous class explicitly:** *which sentences sound clever but say less than they
|
|
75
93
|
appear to?* Those read fine and carry nothing, and they are the ones a knowing reader waves
|
|
76
94
|
through.
|
|
77
95
|
5. **Apply the fixes — as rewrites of the whole thought, never as excisions.** See the rule below.
|
|
78
|
-
6. **Re-run on the fix.** An edit is not done until the
|
|
79
|
-
|
|
96
|
+
6. **Re-run on the fix, with both personas.** An edit is not done until the engineer parses the
|
|
97
|
+
replacement AND the reviewer finds its owner and its register. A fix for the engineer that goes
|
|
98
|
+
colloquial is a new \`REGISTER\` finding, and the reverse holds too. One confirming round; do not
|
|
99
|
+
loop past it.
|
|
80
100
|
|
|
81
101
|
## 🔴 Hand the reader WHOLE PARAGRAPHS, never \`+\` lines
|
|
82
102
|
|
|
@@ -120,7 +140,8 @@ findings:
|
|
|
120
140
|
|
|
121
141
|
- 🔴 **No context in the prompt. Ever.** Not the title, not the abstract, not "this is a paper about
|
|
122
142
|
agent rules files". Every sentence of background handed to the reader is a sentence of confusion
|
|
123
|
-
they will no longer report.
|
|
143
|
+
they will no longer report. The one exception is the venue's name, given to the reviewer persona:
|
|
144
|
+
judging register without knowing the venue is guessing.
|
|
124
145
|
- 🔴 **A fix that removes the flagged construction and keeps the compression is not a fix.** Proven
|
|
125
146
|
twice in one hour: *"not through any defect in how we write it, but because that is what English
|
|
126
147
|
is"* → *"that is what English is for"* (tic gone, meaning inverted into nonsense); *"the agent
|
|
@@ -4,7 +4,7 @@ description: Use when the numbers exist and it's time to WRITE the paper — "dr
|
|
|
4
4
|
allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Skill]
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
<!-- vigiles:sha256:
|
|
7
|
+
<!-- vigiles:sha256:c8d25c21dc01a742 compiled from skills/draft-paper/SKILL.md.spec.ts -->
|
|
8
8
|
|
|
9
9
|
# draft-paper — prose that survives review and gets cited
|
|
10
10
|
|
|
@@ -78,7 +78,7 @@ grade.
|
|
|
78
78
|
|
|
79
79
|
## Run the prose through the PAPER suite's QA (do not skip — and do not use the blog skills)
|
|
80
80
|
Before any review pass, run the draft through the paper-side prose QA — it catches what a self-read won't:
|
|
81
|
-
- **`grade-paper-writing`** — the
|
|
81
|
+
- **`grade-paper-writing`** — the 10-dim rubric + the PERSONA cold-read stall pass (a committed
|
|
82
82
|
non-academic persona, per-section — the localized "wait, what does that even mean?" axis authors are
|
|
83
83
|
blind to). Its avoid-list grep also strips the AI-writing tropes (hedge-stacking, "it's worth
|
|
84
84
|
noting", limp connectives, fake balance) that make a draft read unserious to a human PC.
|
|
@@ -84,7 +84,7 @@ grade.
|
|
|
84
84
|
|
|
85
85
|
## Run the prose through the PAPER suite's QA (do not skip — and do not use the blog skills)
|
|
86
86
|
Before any review pass, run the draft through the paper-side prose QA — it catches what a self-read won't:
|
|
87
|
-
- **\`grade-paper-writing\`** — the
|
|
87
|
+
- **\`grade-paper-writing\`** — the 10-dim rubric + the PERSONA cold-read stall pass (a committed
|
|
88
88
|
non-academic persona, per-section — the localized "wait, what does that even mean?" axis authors are
|
|
89
89
|
blind to). Its avoid-list grep also strips the AI-writing tropes (hedge-stacking, "it's worth
|
|
90
90
|
noting", limp connectives, fake balance) that make a draft read unserious to a human PC.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: grade-paper-writing
|
|
3
|
-
description: Use when asking "does this paper read well?" / "is the writing any good?" / "it reads like a wall of text and jargon" / "grade the writing" on a draft. Grades WRITING CRAFT only —
|
|
3
|
+
description: Use when asking "does this paper read well?" / "is the writing any good?" / "it reads like a wall of text and jargon" / "grade the writing" on a draft. Grades WRITING CRAFT only — ten dimensions 1–5 (Title, Abstract, Intro architecture, Structure, Prose clarity, Jargon discipline, Landing-the-point, Figure economy, Honesty-without-hedge-stacking, Register distance to the target venue) against how the best-written papers read (Peyton Jones, McEnerney, Gopen & Swan; exemplars Trusting Trust, Carlini, Greshake) AND against 2–3 accepted papers of the target venue, naming the offending sentence and the fix for each. Runs the cold-read stall pass with TWO committed personas (a non-academic engineer per section, and a workshop reviewer skimming abstract, introduction and conclusion) whose stall inventory — not the rubric number — is the readability gate other skills consume (pc-panel-review, paper-adversarial-review, harden-paper). Defaults to a blind multi-grader panel; after fixes, mandates the claims-preservation diff (row `claims`). NOT a content/defect review (paper-adversarial-review / pc-panel-review), NOT a structural cut plan (tighten-paper — run that first on a bloated draft), NOT venue-bar content strength (study-accepted-papers). Compose with harden-paper (which calls it), draft-paper (generative counterpart), render-paper.
|
|
4
4
|
allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, Skill]
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
<!-- vigiles:sha256:
|
|
7
|
+
<!-- vigiles:sha256:baf1f69df2502086 compiled from skills/grade-paper-writing/SKILL.md.spec.ts -->
|
|
8
8
|
|
|
9
9
|
# grade-paper-writing — grade how the paper READS, then fix it sentence by sentence
|
|
10
10
|
|
|
@@ -16,7 +16,7 @@ doesn't drive home how crazy the situation is"* — which is a writing problem,
|
|
|
16
16
|
which the defect-hunting skills will pass right over.
|
|
17
17
|
|
|
18
18
|
Grounding (do NOT re-derive — read it): `../paper-pipeline/references/writing-craft.md` holds the craft
|
|
19
|
-
rules, the exemplar lessons, and the full
|
|
19
|
+
rules, the exemplar lessons, and the full ten-dimension rubric with 1/5 anchors. This skill applies it.
|
|
20
20
|
|
|
21
21
|
## The frame to hold while grading (from the reference)
|
|
22
22
|
The papers that make a human care share three moves: **(1) open on a problem/assumption the reader already
|
|
@@ -25,6 +25,14 @@ repeatable sentence.** Grade the draft against that trio, plus McEnerney's test
|
|
|
25
25
|
for the reader, or just record the author's thinking?* — and Gopen/Swan's sentence mechanics (payload in
|
|
26
26
|
the stress position, subject next to verb, one idea per sentence).
|
|
27
27
|
|
|
28
|
+
🔴 **Every push in this rubric has a floor as well as a ceiling.** The craft rules above pull toward
|
|
29
|
+
short, plain, punchy sentences, and each mechanical check below caps something: jargon, length, hedges,
|
|
30
|
+
connectives. A rubric in which every check is a ceiling has one equilibrium — terse assertions with no
|
|
31
|
+
signposting and no stated owner — and reviewers call that a blog post (*"overly literary"*, *"some
|
|
32
|
+
sentences are too informal"*, *"readers are often required to infer the intended relationships between
|
|
33
|
+
claims"*). The floor is the venue's own register: dimension #10 measures the distance to it, and no fix
|
|
34
|
+
this skill proposes may move the text further from it than it already is.
|
|
35
|
+
|
|
28
36
|
## Execution model — run the graders as subagents (context forks), by default
|
|
29
37
|
The blind panel (≥3 graders) and the cold-read stall pass **run in fresh subagents, not inline** — for two
|
|
30
38
|
reasons: (a) grading dumps the whole paper + long stall inventories into context, which gunks up the main
|
|
@@ -77,6 +85,21 @@ they supplied it.
|
|
|
77
85
|
Give the passage **as text in the prompt**, not as a file path. A path invites reading the
|
|
78
86
|
neighbours, and reading the neighbours is how this pass fails silently.
|
|
79
87
|
|
|
88
|
+
### Two readers, and both run
|
|
89
|
+
|
|
90
|
+
The pass runs two committed personas, each in its own subagent. Neither replaces the other: they
|
|
91
|
+
stall on different sentences.
|
|
92
|
+
|
|
93
|
+
| persona | reads | stalls on |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| **the engineer** — a strong practitioner outside academia (`Sam` in the reference) | every section, one subagent per section | terms, walls, sentences that mean nothing to someone who does not already hold the idea |
|
|
96
|
+
| **the workshop reviewer** — a PC member at the target venue with 40 minutes for the paper, Confidence 3 | the abstract, the introduction and the conclusion, skimmed in that order | a sentence whose result has no owner (the authors? a cited work? a population?), a relation between claims left for the reader to infer, and anything that does not read like a paper at this venue |
|
|
97
|
+
|
|
98
|
+
The engineer cannot report the second column by construction: he does not know what a paper at the
|
|
99
|
+
venue sounds like, and a sentence with no stated owner reads to him as confident, not as ambiguous.
|
|
100
|
+
The reviewer persona's full prompt is in the reference, next to the engineer's. Its findings go into
|
|
101
|
+
the same stall inventory, under their own classes (7 and 8 below).
|
|
102
|
+
|
|
80
103
|
### The one question, per sentence
|
|
81
104
|
|
|
82
105
|
> **What does this sentence claim? Restate it in your own words.**
|
|
@@ -98,6 +121,8 @@ every 2026-08-05 defect lived.
|
|
|
98
121
|
| 4 | 🔴 **means nothing** | every word is known, the sentence parses grammatically, and the reader still cannot say what it claims | *"the state to remove is not the rule but its claim about itself"* · *"constructions nobody built"* |
|
|
99
122
|
| 5 | 🔴 **sounds clever, carries nothing** | reads smoothly, feels like a payoff, and its content is a restatement or is borrowed from a section the reader has not read | *"nine deletions against four fixes is §5.1's cheap way out, winning again"* |
|
|
100
123
|
| 6 | 🔴 **vague heading** | a heading naming no concrete object — no linter, no configuration, no agent, no file | *"Three answers, all of them after the fact"* · *"The configuration nobody resolves"* |
|
|
124
|
+
| 7 | 🔴 **whose result?** (reviewer persona) | the reader cannot tell whether a claim is a property of the world, a cited finding, or the authors' own measurement | *"asked twice about the same repositories, it changes its mind on a fifth"* — the paper's own experiment, read as a fact about LLMs |
|
|
125
|
+
| 8 | 🔴 **off-register** (reviewer persona) | a sentence the venue's accepted papers would not contain: an aphorism, a fragment, a colloquial closing line, an unmarked jump between claims | *"Measure the bill, not the syllables."* — quoted back by a reviewer as "too informal" |
|
|
101
126
|
|
|
102
127
|
Class 5 is the one a knowing reader always waves through, because it reads *well*. Ask for it by
|
|
103
128
|
name — "which sentences sound clever but say less than they appear to?" — or it will not be reported.
|
|
@@ -133,11 +158,12 @@ is what happened.
|
|
|
133
158
|
2. **Run the cold-read stall pass FIRST — the full specification is below, under "The stall pass".**
|
|
134
159
|
It was previously a pointer to a reference section that did not exist, which is why the pass drifted
|
|
135
160
|
into "log where I stumbled" and stopped catching the class it exists for.
|
|
136
|
-
2. **Score all
|
|
161
|
+
2. **Score all ten dimensions 1–5** using the anchors in the reference, on the **absolute scale** defined
|
|
137
162
|
there (5 = best-in-field, **3 = the default for a solid paper**; most dimensions are 2–3). Weight Prose
|
|
138
|
-
(#5), Jargon (#6), Landing (#7) ×2 —
|
|
163
|
+
(#5), Jargon (#6), Landing (#7) and Register (#10) ×2 — the first three are where "wall of jargon"
|
|
164
|
+
lives, the fourth is where "blog post" lives. Report raw /50 + weighted /70.
|
|
139
165
|
**Do NOT trust a single grade.** A lone grader — especially one that just wrote or verified the paper —
|
|
140
|
-
anchors optimistic; a
|
|
166
|
+
anchors optimistic; a 60/70-looking number is suspect until confirmed. So **when the score matters, run a
|
|
141
167
|
blind panel: ≥3 independent graders (fresh subagents, ideally an adversarial model like Fable), each
|
|
142
168
|
blind to any prior score, to each other, and to the "it improved" framing — given only the current page
|
|
143
169
|
and the field's best.** Report the **distribution (per-dimension + overall min / median / max)**, not one
|
|
@@ -146,6 +172,18 @@ is what happened.
|
|
|
146
172
|
3. **For every dimension scoring ≤3, name the specific offending sentence or section** and write the fix —
|
|
147
173
|
not "tighten the prose" but the rewritten sentence, or "move the point from ¶3 to ¶1", or "gloss
|
|
148
174
|
`operation-normalized` in plain words at first use." Fixes must be applyable, not vibes.
|
|
175
|
+
3a. **Grade #10, register distance, against the venue's own papers — not against the exemplars.**
|
|
176
|
+
Take 2–3 papers accepted at the target venue (or, for a first-edition workshop, at its parent
|
|
177
|
+
conference) in the same paper type: fetch them from the proceedings or the program page, or use the
|
|
178
|
+
ones the author supplies. Read the abstract, the introduction and the conclusion of each beside the
|
|
179
|
+
draft's, and record, for both sides: how each result is owned (*we measured* · a citation · a named
|
|
180
|
+
population), how often a point is made by contrast (*not X but Y*, *rather than*, *instead of* —
|
|
181
|
+
the measured difference between this corpus and accepted papers), sentence length and fragments,
|
|
182
|
+
and whether any sentence is an aphorism or a closing punchline. The
|
|
183
|
+
score is the distance: 5 = a reviewer could not tell the draft from the reference papers by register;
|
|
184
|
+
1 = it reads as a different genre. Quote the reference sentence beside each draft sentence you flag.
|
|
185
|
+
If no accepted paper can be fetched or supplied, write `#10: not graded — no reference papers` and
|
|
186
|
+
say which were tried; a register score from memory is the guess this dimension exists to replace.
|
|
149
187
|
4. **Find the paper's three-move opportunities:** what held assumption could open it? what is its single
|
|
150
188
|
most visceral concrete instance (lead with that, not the mean)? what one sentence should the reader
|
|
151
189
|
quote? If the draft is missing any, that's the highest-leverage fix.
|
|
@@ -210,7 +248,7 @@ is what happened.
|
|
|
210
248
|
8. **Run the avoid-list grep (mechanical).** Grep the source for the slop / web-slang / filler / hype words
|
|
211
249
|
in `../paper-pipeline/references/writing-craft.md` → "The avoid-list", and report every hit with its line number and a
|
|
212
250
|
replacement. These are scrutinize-words, not absolute bans — but each hit is a readability debit against
|
|
213
|
-
dimension #6 (Jargon) and the
|
|
251
|
+
dimension #6 (Jargon) and the north star — readable by the target reader, in the venue's register. (This session's miss that motivated
|
|
214
252
|
it: "listicle" survived into a submitted-ready AISec draft.)
|
|
215
253
|
7. **Wall-of-text sweep (see `writing-craft.md` → "The wall-of-text check").** Flag any paragraph running
|
|
216
254
|
>~15 source lines / ~150 words or covering >3 sub-points — a visual wall the reader's eye slides off
|
|
@@ -224,7 +262,7 @@ is what happened.
|
|
|
224
262
|
isn't strong enough" and "nothing here is quotable."
|
|
225
263
|
|
|
226
264
|
## Output
|
|
227
|
-
1. **Scorecard** —
|
|
265
|
+
1. **Scorecard** — ten dimensions with one-line justification each; raw /50 + weighted /70. When a blind
|
|
228
266
|
panel was run (the default when the score matters), report the **distribution** — per-dimension and
|
|
229
267
|
overall min / median / max across graders — not a single number, and name any dimension they split on.
|
|
230
268
|
Lead with the two or three dimensions dragging it down, ranked.
|
|
@@ -299,19 +337,31 @@ Mechanical leg: `paper-lint`'s plain-language pass flags any sentence carrying t
|
|
|
299
337
|
citation groups, or five or more reference numbers in under 45 words. It cannot judge whether the
|
|
300
338
|
prose is *good*; it reliably catches this one shape, which is the shape that recurs.
|
|
301
339
|
|
|
302
|
-
**And the words themselves, not only the sentences.** *
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
340
|
+
**And the words themselves, not only the sentences.** *Utilise* means *use*. The "Jargon discipline"
|
|
341
|
+
dimension below does not catch this, because the word looks perfectly at home — judgment slides right
|
|
342
|
+
past it. What catches it is a list: `paper-lint` carries ~30 words with a plainer equivalent (utilise ·
|
|
343
|
+
constitutes · prior to · necessitates · facilitates · leverage · albeit · in order to …) and names the
|
|
344
|
+
replacement in the nudge.
|
|
345
|
+
|
|
346
|
+
🔴 **The swap is two-sided: replace a word only when the plain word stays in academic register.**
|
|
347
|
+
*Utilise → use* and *in order to → to* pass: the replacement is what the venue's own papers write.
|
|
348
|
+
*Adherence → following*, *demonstrates → shows* in a results sentence, *methodology → how we did it*
|
|
349
|
+
do not pass when the reference papers of dimension #10 use the first form — there the plain word is a
|
|
350
|
+
step toward a blog post, and the finding is withdrawn. Keep the list narrow — only words where the swap
|
|
351
|
+
changes neither meaning nor register — and never rewrite a cited work's title to obey it.
|
|
352
|
+
|
|
353
|
+
**Signposting is the register, not a tic, and this skill never removes it on style grounds.** Frame
|
|
354
|
+
markers and relation words — *we show*, *this section*, *first … finally*, *in contrast*, *therefore*,
|
|
355
|
+
*however* — are how academic prose tells the reader what kind of claim comes next and how it relates to
|
|
356
|
+
the last one. Their count does not separate a draft from accepted papers (see "Contrast framing"
|
|
357
|
+
below); removing them does, in the wrong direction. Flag a connective only when it asserts a relation
|
|
358
|
+
the two sentences do not have (a *therefore* that does not follow), or when it is empty filler (*it is
|
|
359
|
+
worth noting that*). Never flag one for being academic.
|
|
360
|
+
|
|
361
|
+
**Other markers worth a pass:** nominalisation density (*an honest accounting of what the construction
|
|
362
|
+
costs* — abstract nouns doing the work verbs should do) and statistics chained through a paragraph
|
|
363
|
+
instead of sitting in a table. Numbers belong in a table the moment there are more than about six of
|
|
364
|
+
them in one paragraph.
|
|
315
365
|
|
|
316
366
|
|
|
317
367
|
## 🔴 The class the rubric could not see, and why it kept coming back (2026-08-04)
|
|
@@ -330,25 +380,37 @@ them measures words and sentences. The defect is not in the words.
|
|
|
330
380
|
|
|
331
381
|
Two separable failures:
|
|
332
382
|
|
|
333
|
-
### 1.
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
383
|
+
### 1. Contrast framing, and a frame that carries nothing
|
|
384
|
+
|
|
385
|
+
**What separates this corpus from accepted papers is contrast, not signposting — measure that
|
|
386
|
+
first.** Counted with the same counter on five accepted ACSAC 2024/25 ML-security papers against a
|
|
387
|
+
paper of ours: *"not X but Y"* at 35.5 per 10,000 words in ours against at most 4.9 there (and five
|
|
388
|
+
of their six hits were *"not only … but also"*); *"rather than / instead of"* at 19.9 against at most
|
|
389
|
+
5.4. Every sentence that defines its point by what it is not is a sentence whose point the reader
|
|
390
|
+
must reconstruct. **Rewrite heuristic:** state the thing; move the rejected alternative to its own
|
|
391
|
+
sentence, or drop it if nobody proposed it. Check *instead of · rather than · not … but* first,
|
|
392
|
+
against the same count on the reference papers of dimension #10.
|
|
393
|
+
|
|
394
|
+
**Frame markers do not separate us from accepted papers, and are not a target in either direction.**
|
|
395
|
+
Hyland's *frame markers* (*this paper · this section · we show · first … finally · in what follows*)
|
|
396
|
+
measured 0.76–3.1 per 1,000 words on those five accepted papers (median 1.46); the lowest accepted
|
|
397
|
+
paper measured is 0.76, and ours sat inside that range. So neither "remove signposting" nor "add
|
|
398
|
+
signposting to reach a number" is a fix. A published average from a different counter (Hyland's
|
|
399
|
+
~5 per 1,000) says nothing about where a venue's floor lies.
|
|
400
|
+
|
|
401
|
+
What IS a defect is a frame that carries nothing. *"Two findings come first, because they bind
|
|
402
|
+
whatever else you build"* says nothing about rules files, agents, or repositories: the frame is
|
|
403
|
+
there, and the claim it announces is not. List the frames whose announced content never arrives
|
|
404
|
+
within the next two sentences; those are the findings. **Rewrite heuristic:** keep the frame and make
|
|
405
|
+
it carry the claim. *"Two findings come first, because they bind whatever else you build. Asked the
|
|
406
|
+
same question twice…"* → *"We first report two properties of the model that constrain any harness
|
|
407
|
+
built on it. Asked the same question twice with identical inputs, it changed its verdict on 21.5% of
|
|
408
|
+
rows (Section 4.5)."* The frame now names what follows, and the sentence after it says whose
|
|
409
|
+
measurement it is.
|
|
410
|
+
|
|
411
|
+
⚠️ **Vocabulary lists are not a register signal.** *robust*, *significant*, *comprehensive* and the
|
|
412
|
+
rest of the AI-tells vocabulary fire on every one of the five accepted papers. Flag such a word only
|
|
413
|
+
when it is empty in its sentence, never as evidence of a machine or of the wrong register.
|
|
352
414
|
|
|
353
415
|
### 2. The qualification eats the claim
|
|
354
416
|
|
|
@@ -388,9 +450,11 @@ one sentence.
|
|
|
388
450
|
They are the only two sections most readers finish, and the abstract is the only one every reviewer
|
|
389
451
|
reads before forming a view. Grade them **separately and harder**:
|
|
390
452
|
|
|
391
|
-
-
|
|
453
|
+
- no frame that announces a claim and then does not make it; *"We show that…"* naming the authors'
|
|
454
|
+
own result is the register of an abstract, not a defect;
|
|
392
455
|
- first sentence is about the world, never about the document;
|
|
393
|
-
- no number arrives without the unit it counts (*"21.5% of rows"* — rows of what?)
|
|
456
|
+
- no number arrives without the unit it counts (*"21.5% of rows"* — rows of what?) or without its
|
|
457
|
+
owner — the authors' measurement, a cited work, or a named population;
|
|
394
458
|
- the last sentence of each is a **conclusion**, not an announcement of one;
|
|
395
459
|
- nothing may refer forward to a section the reader has not read.
|
|
396
460
|
|
|
@@ -400,8 +464,9 @@ one did, and it was the worst section in the paper by measured density both time
|
|
|
400
464
|
|
|
401
465
|
### What is NOT mechanizable here
|
|
402
466
|
|
|
403
|
-
Whether a frame marker
|
|
404
|
-
whether a hedge is honest or defensive.
|
|
467
|
+
Whether a frame marker carries its claim (*"we claim nothing there"* genuinely scopes one) and
|
|
468
|
+
whether a hedge is honest or defensive. The mechanical leg that does exist: `tex/claim-provenance`
|
|
469
|
+
reports every sentence of the body that holds a number and no owner. Count them, surface them, and leave the verdict to a reader.
|
|
405
470
|
The counter's job is that nobody can say afterwards they did not know.
|
|
406
471
|
|
|
407
472
|
## Compose with
|