From 0f6c8fdaf4cb9f51fa89f27f756b547bee644fc3 Mon Sep 17 00:00:00 2001 From: GiggleLiu Date: Thu, 10 Sep 2026 20:06:44 +0800 Subject: [PATCH 1/7] how-to-technical-writing: simple words rule and shared writing checklist Rewrite the style guide in its own plain style, rename the connectives rule to "simple words; preserve technical words", and move the writing checklist (guidelines 1-5, 7) from review-paper into how-to-technical-writing/checklist.md so the writing guide has one home. review-paper/checklist.md keeps only the review-process items (gate, verification, journal fit, delivery), rewritten in short sentences. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_018cc6n2NyTUNUDQ7LhzZDur --- .gitignore | 1 + CLAUDE.md | 2 +- skills/how-to-technical-writing/SKILL.md | 109 +++++++++--------- skills/how-to-technical-writing/checklist.md | 52 +++++++++ skills/review-paper/SKILL.md | 6 +- skills/review-paper/checklist.md | 114 ++++++------------- skills/write-paper/SKILL.md | 2 +- 7 files changed, 150 insertions(+), 136 deletions(-) create mode 100644 skills/how-to-technical-writing/checklist.md diff --git a/.gitignore b/.gitignore index 6ba75a3..a3c8d5b 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,4 @@ docs/superpowers/ docs/superpowers/specs/ docs/survey-question-classification.md docs/test-reports/ +.lavish diff --git a/CLAUDE.md b/CLAUDE.md index 1ecf185..9070c02 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,7 +30,7 @@ The 15 skills in `skills/` are each defined by a `SKILL.md` with YAML frontmatte - **how-to-build-kb** — Turns a list of picked papers (from `survey`, `know-me-better`, or `autoresearch`) into verified KB entries: Semantic Scholar / CrossRef lookup, `.raw/` JSON, `references.bib` append via `append_bibtex.py`, `INDEX.md` regeneration, and `NOTES.md` (landscape, open problems, bottlenecks). Non-interactive; never generates BibTeX from memory. - **how-to-write-ideas-report** — Writes the proposal-style ideas report (research question, novelty, MVE, success/hope/pivot signals, risks, venue, verified references) from a finished `brainstorm-ideas` log. Follows `skills/how-to-write-ideas-report/references/writing-workflow.md`. -- **how-to-technical-writing** — The shared writing style guide: sentence- and paragraph-level rules (one concept per sentence, direct to the point, name the earlier context instead of "obviously", plain connectives with every technical word kept, no undrawn metaphors, locality, say it once), a hunt-for/fix table for language passes, and guardrails naming which fixes are comment-only because they change content. `write-paper` drafts by it, `review-paper` reviews by it, and `how-to-write-ideas-report` / `survey` report mode follow it for report prose. Notation and figure rules stay in `write-paper`. +- **how-to-technical-writing** — The shared writing style guide: sentence- and paragraph-level rules (one concept per sentence, direct to the point with key information early, simple words with every technical word kept, no undrawn metaphors, locality, say it once), a hunt-for/fix table for language passes, a `checklist.md` with the rules as checkable items, and guardrails naming which fixes are comment-only because they change content. `write-paper` drafts by it, `review-paper` reviews by it, and `how-to-write-ideas-report` / `survey` report mode follow it for report prose. Notation and figure rules stay in `write-paper`. - **how-to-review-figure** — Reviews the *visual design quality* of a figure, plot, or diagram and prints a scorecard. Source-aware (renders the figure to a raster to look at it via `helpers/render.py`, reads matplotlib/Typst/SVG source so fixes can cite a line), report-only, terminal-first. Scores against an 18-rule rubric (11 general — alignment, proximity, color, hierarchy, contrast, colorblind-safety, …; plus 7 scientific-plot rules — text size, line weight, space use, chartjunk, legend, cross-panel consistency, resolution). Distinct from `review-paper` (which checks whether a figure is cited/discussed in the text, not how it looks) and `write-paper` (which authors figures). Full rubric in `skills/how-to-review-figure/checklist.md`. - **how-to-flow** — Autonomous deep-thinker that conquers one hard goal via a CDCL/DPLL-style search loop: a **preflight gate** (is the goal testable? are all context/KB facts loaded?), then iterate *decide* (**what-if**: assume a condition, test "closer to goal?" + "easier to achieve?") → *propagate* (**simulate**: run consequences forward, reflect; may fan out 2–3 subagents on wide forks) → *learn* (note a reusable clause after **every** trial) → *backjump* (non-chronological, to the real cause) → *pivot* (meta-restart: re-aim to an equally-valuable easier goal when stuck, keeping all notes). Domain-agnostic and KB-optional. Writes a per-trial journal to `docs/flow/.md` (template in `skills/how-to-flow/journal-template.md`). Terminates SOLVED / PIVOTED-SOLVED / EXHAUSTED (≤3 pivots). Distinct from `brainstorm-ideas` (open-ended, collaborative) — `how-to-flow` is goal-locked and autonomous. - **how-to-download-ref** — Adds one or many new arXiv IDs / DOIs to a knowledge base (`/.knowledge/` by default; `advisors//.knowledge/` when invoked from advisor flows). Fetches Semantic Scholar metadata, downloads PDFs (with SciHub fallback); when the user opts in, also fetches arXiv LaTeX sources and renders those refs (incl. DOI entries with an arXiv preprint) from flattened LaTeX (`full_text: latex`) via `--tex-source`, otherwise all refs render via `pymupdf4llm`. Regenerates `INDEX.md`, appends to the KB's `references.bib`. Supports `--from-bib` for bulk operations on an existing BibTeX. diff --git a/skills/how-to-technical-writing/SKILL.md b/skills/how-to-technical-writing/SKILL.md index 61818d8..3c22287 100644 --- a/skills/how-to-technical-writing/SKILL.md +++ b/skills/how-to-technical-writing/SKILL.md @@ -5,72 +5,73 @@ description: Agentic trigger. Use when writing or polishing scientific prose at ## Installed resources -Keep the working directory at the user's project. Resolve this loaded `SKILL.md` -with `Path(path).resolve()` before locating resources; follow symlinks. Bare -`helpers/`, `references/`, and template paths are relative to that real skill -directory. A path written as `skills//...` means the installed `` -skill's directory from the agent's skill catalog, not a path in the user's project. -Locate each dependency by its public skill name; copied skills need not be siblings. -If a dependency is absent, report the missing skill and install it before that step. -Shared writing files are bundled in `how-to-write-ideas-report/references/`. +Keep the working directory at the user's project. Resolve this `SKILL.md` with +`Path(path).resolve()` to follow symlinks. Bare `helpers/`, `references/`, and +template paths are relative to that real directory. `skills//...` refers +to the installed skill found by public name in the agent's catalog, not the +user's project. Dependencies need not be siblings; report and install missing +skills before the dependent step. Shared writing files are bundled in +`how-to-write-ideas-report/references/`. +# Writing style guide -# Writing Style Guide +These sentence and paragraph rules guide `write-paper` drafts, `review-paper` findings and proposed fixes, and `how-to-write-ideas-report` and `survey` report prose. -The sentence- and paragraph-level rules shared by every skill that produces or reviews scientific prose: `write-paper` applies them while drafting, `review-paper` hunts for their violations and proposes fixes, and `how-to-write-ideas-report` and `survey` report mode follow them for report prose. Notation and figure rules stay in `skills/write-paper/SKILL.md` (Notation Rulebook, Figure Rulebook); the reasons behind every rule are in `skills/write-paper/references.md`, and the model paper that executes them is `skills/write-paper/sources/1807.01815_Ho2019_quantum-scars.md`. +Related resources: -The rules were distilled from Martinis, von Delft, and a language-polish checklist for teaching material. The guardrails at the end exist because several rules are dangerous when applied mechanically to a research manuscript. +- Checkable form of these rules: `checklist.md`. +- Notation Rulebook and Figure Rulebook: `skills/write-paper/SKILL.md`. +- Reasons behind every rule: `skills/write-paper/references.md`. +- Model paper: `skills/write-paper/sources/1807.01815_Ho2019_quantum-scars.md`. ---- +The rules come from Martinis, von Delft, and a language-polish checklist for teaching material. The guardrails prevent mechanical edits from changing manuscript content. ## Rules -Clarity outranks every rule below; when two collide, keep the clearer sentence. - -- **One concept per sentence, about 20 words.** Twenty is a target, not a ceiling. A sentence with a semicolon, a colon-plus-clause, and a trailing "so …" is three sentences; keep the logical word ("so", "because") at the head of the next one. Do not split a sentence that wraps a display equation or binds a hypothesis to its conclusion. If two concepts must coexist, make sure both are already familiar to the reader. -- **Direct to the point.** Say the thing. No content-free opener ("In this section we discuss several aspects of …"), no "Notice that" / "As one can see" / "Interestingly,", and no meta-talk that adds nothing ("as promised above"). A sentence that names the section's job or points the reader to a result is signposting, not warm-up, and stays. -- **Name the earlier context instead of "obviously".** A claim that rests on something earlier names it: "Because Eq. (3) is linear in $t$, …", not "Clearly, …". Never tell the reader a step is obvious or trivial. The reason must already exist in the manuscript; if it does not, ask the author instead of writing one from general knowledge. -- **Plain connectives, but keep every technical word.** "so" over "hence" and "thus"; "also" over "likewise"; "use" over "utilize". Swap only connectives and filler that have no mathematical reading. Never swap a verb, quantifier, or adjective inside a mathematical statement: "arbitrary", "determined by", "identify with", and "the converse" are technical. Never replace a term the field uses ("decoherence", "ansatz", "thermalize") with a simpler word: if it is in the textbook or a referee's vocabulary, it stays. -- **No metaphor the paper does not draw.** "in disguise", "the clue", "recipe", "cashes in" go; use the plain word ("in different notation", "start from", "formula"). Replace only when a plain word carries the identical meaning; field idioms such as "the gap survives disorder" are technical usage and stay. A physical intuition in prose stays when the sentence itself makes it precise; it never requires a new figure, and it never requires an existing figure to depict it. -- **Active voice for actions.** "We measured" beats "measurements were performed." Reserve passive only for things genuinely without an agent. Put the verb early and give it a concrete subject. -- **Concrete verbs over nominalizations.** "We adopt the new notation" beats "Adoption of the new notation is undertaken." -- **No stacked asides, no idle adverbs.** At most one parenthesis or dash aside per paragraph; make the rest sentences. Delete intensifiers and empty evaluatives only: "very", "quite", "rather", "interestingly", "importantly", "notably". Hedges of magnitude or certainty are content and stay: "approximately", "nearly", "at most", "typically", "numerically", "only", "exactly". Drop a "not X but Y" frame only when X appears nowhere else in the argument; when the contrast with X is the result, the frame stays. -- **Prose carries ideas; calculations go to displays.** A body sentence states an idea, an intuition, or a logical step. Two or more inline computations in one paragraph become one display followed by one sentence saying what it shows. Whether that display earns its place is the Notation Rulebook's call. Never inline or cut an equation whose label is referenced elsewhere; in a letter, move algebra to the supplement rather than deleting a step the reader needs to reproduce the result. -- **Locality (Theory, Methods, Results, Analysis).** A paragraph stays on one object; a section stays on its job. Do not connect two concepts, preview a later section, or add a second interpretation the argument never uses. A cross-reference is fine when the current step depends on it, and the sentence says why ("by the linearity of Eq. (3)"). The Introduction and Conclusions are exempt: prior-work context, cross-field connections, and implications live there by design. -- **Say it once (within the body).** If the main-result sentence states it, the paragraph after the equation does not restate it. If a paragraph's last sentence repeats its first, cut one. Restatement across the abstract, introduction, and conclusions is deliberate (Iron Rule 2), and so is naming a main result more than once. -- **No overclaim smuggled in by prose.** A rewritten sentence keeps every count, number, and qualifier right ("the three approximations" when four were made is a bug). "Always", "only", and "never" stay only if nothing later in the paper contradicts them. -- **Match grammar where ideas already run in parallel.** When a sentence compares or contrasts two things, or a list already exists, give the items the same grammatical shape. This is a rule about wording, not layout: prose stays prose. Do not turn a paragraph into a bulleted list, and do not add a list a journal would not print; a paper reads as an argument, and lists break its flow. -- **Signposting.** Use phrases like *"This is our main result," "We now turn to," "In summary,"* to orient the reader. The reader cannot tell which sentence carries the punchline unless you say so. The model paper signposts every turn — *"Specifically," "Conversely," "Most surprisingly,"* — so the reader always knows whether a sentence narrows, contrasts, or escalates. -- **Each paragraph: one job.** Topic sentence at the top, supporting detail in the middle, transition or stress at the end. +Clarity outranks these rules. When they conflict, keep the clearer sentence. ---- +### Conceptual clarity and semantic coherence -## Hunt table (for reviewing and for the final language pass) +- **Explain concepts with existing concepts.** Do not use concepts never explained, or that are not a common sense to explain a new idea. +- **One job per paragraph.** Each paragraph has its own mission. Start with a topic sentence, support it with detail, and end with a transition or emphasis. Do not mix different jobs in the same paragraph. +- **Locality rule.** Keep each paragraph on one object and each section on its job. Avoid connecting to concepts not within current scope, previewing later sections, or adding unused interpretations. Keep cross-references only when the current step depends on them, and say why: "by the linearity of Eq. (3)". In paper writing, abstracts, introduction, and conclusions are exempt. +- **Do not repeat yourself.** Cut sentences that do not carry new information or new examples. -What to hunt for at the sentence level, with the fix. Each finding cites its row. A passage that trips no row stays untouched. Rows marked **comment only** are never applied as edits, even after approval: the author writes those words. +### Narrative and wording choices -| Hunt for | Fix | -|---|---| -| A sentence over ~25 words, or two clauses joined by a semicolon or "and … so …" | Split. Keep the logical word ("so", "because") at the start of the second sentence. Leave whole a sentence that wraps a display equation or binds a hypothesis to its conclusion. | -| A paragraph that restates the main-result sentence, the equation, or its own opening | Delete the restatement; keep the canonical statement. | -| "Notice that", "As one can see", "Interestingly," "It is worth noting" | Rewrite as a declarative statement of the fact. | -| "Obviously", "clearly", "trivially", or an assertion with no visible reason | Name the earlier context in one clause: which equation, figure, or section gives it. **Comment only** when that reason is not already in the manuscript. | -| A metaphor or idiom ("in disguise", "clue", "recipe", "cashes in") | The plain word ("in different notation", "start from", "formula"), only when it carries the identical meaning. Field idioms ("the gap survives disorder") stay. | -| A Latinate connective where an everyday one exists ("hence", "thus", "likewise", "utilize") | "so", "also", "use". Connectives and filler only. Never swap a verb, quantifier, or adjective in a mathematical statement: "arbitrary", "determined by", "identify with", "the converse" are technical. | -| A count or qualifier the prose gets wrong ("the three approximations" when four were made) | Correct it or drop the number. | -| "Always", "only", "never" that a later section contradicts | Add the qualifier, or cut the claim. | -| Two or more inline computations in one paragraph | One display; one sentence names what it shows. Cut the algebra if it earns no display. | -| More than one aside per paragraph; an intensifier or empty evaluative ("very", "quite", "interestingly", "notably") | Cut the aside or make it a sentence; delete the intensifier. Hedges of magnitude or certainty ("approximately", "at most", "typically", "only", "exactly") are content and stay. | -| A "not X but Y" frame where X appears nowhere else in the argument | State Y. **Comment only**; when the contrast with X is the result, the frame stays. | -| Empty meta-talk ("this answers the question posed above", "as promised") | Delete. A signpost that names the section's job or points to a result is not meta-talk. | -| In Theory, Methods, Results, or Analysis: a paragraph that drifts to a second object, previews a later section, or adds an interpretation the argument never uses | **Comment only.** Propose cutting the digression or moving it to where that object is the subject. Keep a cross-reference only when the step depends on it, and say why. Introduction and Conclusions exempt. | +- **Cut long sentences.** Use length as a review signal, not a target. Split overloaded clauses into separate sentences, retaining logical links such as "so" or "because". Keep sentences that wrap a display equation or bind a hypothesis to its conclusion whole. +- **State the point directly.** Place key information near the beginning of the sentence. +- **Simple words; preserve technical words.** Explain ideas with simple words rather than fancy ones. Prefer "so" to "hence" or "thus", "also" to "likewise", "use" to "utilize", "show" to "demonstrate", and "start" to "commence". Replace only everyday words, connectives, and filler without mathematical meaning. Never replace verbs, quantifiers, or adjectives in mathematical statements, including "arbitrary", "determined by", "identify with", and "the converse". Keep field terms such as "decoherence", "ansatz", and "thermalize". Textbook and referee vocabulary stays. +- **No metaphor.** +- **Active voice for actions.** Prefer "We measured" to "measurements were performed." Reserve passive for things without an agent. Put the verb early with a concrete subject. +- **Concrete verbs over nominalizations.** Prefer "We adopt the new notation" to "Adoption of the new notation is undertaken." +- **Prose carries ideas; calculations go to displays.** Body sentences state ideas, intuitions, or logical steps. Combine two or more inline computations in a paragraph into one display, followed by one sentence explaining it. +- **Parallel grammar for parallel ideas.** Give comparisons, contrasts, and existing list items the same grammatical shape. Preserve prose layout; do not turn paragraphs into bullets or add lists a journal would not print. Papers develop arguments, and lists interrupt their flow. +- **Signposting.** Mark main results and transitions with "This is our main result," "We now turn to," or "In summary,". The model paper marks every turn with phrases such as "Specifically," "Conversely," and "Most surprisingly," to signal narrowing, contrast, or escalation. ---- +## Hunt table -## Guardrails when applying +Use for reviews and final language passes. Each finding cites its row; leave passages that match none untouched. **Comment only** fixes remain comments even after approval; the author writes the replacement. -- **Change how a sentence is written, never what it says.** Never alter the content of a definition, theorem, or claim while rewording it; never add or remove a claim, figure, or derivation step under a language fix; never replace a field term with a simpler word. -- **Recheck every number, count, and qualifier** a rewritten sentence mentions before moving on. -- **Comment, do not apply, when a fix touches content.** An edit that would change a quantifier or hedge, add a justification the manuscript does not already contain, delete a paragraph as a digression, or remove a "not X but Y" contrast is left as a `[reviewer]` comment (`% [reviewer]` in LaTeX, `// [reviewer]` in Typst, an HTML comment in Markdown). The author writes those words. -- **Leave passing passages alone.** A rewrite is never proposed for the sake of a diff. Every finding names the rule it serves. -- **These are prose rules; they never add figure detail.** Conceptual and overview figures may intentionally omit implementation and timing detail. Judge a figure against its stated explanatory purpose (the Figure Rulebook in `write-paper`), and flag an omission only when it materially misleads the reader about the central mechanism or contradicts a claim the text attributes to the figure. Prefer clarifying a label, a caption, or the nearby sentence over adding graphical detail, and weigh any added detail against readability. Nothing here requires every mechanism discussed in the text to appear in a diagram. +| Hunt for | Fix | +|---|---| +| An overloaded sentence or stacked clauses | Split, retaining logical links such as "so" or "because". Use length as a review signal, not a target. Keep sentences wrapping display equations or binding hypotheses to conclusions whole. | +| Restatement of the main-result sentence, equation, or paragraph opening | Delete the restatement; keep the canonical statement. | +| "Notice that", "As one can see", "It is worth noting" | State the fact directly. | +| Metaphor or idiom: "in disguise", "clue", "recipe", "cashes in" | Use plain wording with identical meaning: "in different notation", "start from", "formula". Keep field idioms such as "the gap survives disorder". | +| Fancy words where simple ones explain the idea: "hence", "thus", "likewise", "utilize", "demonstrate", "commence" | Use "so", "also", "use", "show", "start". Preserve mathematical verbs, quantifiers, and adjectives as required by the technical-words rule. | +| Wrong count or qualifier, such as "three approximations" when there are four | Correct it or drop the number. | +| "Always", "only", "never" contradicted later | Qualify or cut the claim. | +| Two or more inline computations in a paragraph | Combine into one display and one explanatory sentence. Cut algebra that earns no display, subject to the equation and derivation guardrails. | +| Multiple asides in a paragraph, intensifiers, or empty evaluatives | Cut the aside or make it a sentence; delete intensifiers. Preserve magnitude and certainty hedges listed above. | +| "Not X but Y" with X absent elsewhere in the argument | Propose stating Y. **Comment only.** Keep the frame when the contrast is the result. | +| Empty meta-talk: "this answers the question posed above", "as promised" | Delete. Keep signposts naming the section's job or pointing to a result. | +| In Theory, Methods, Results, or Analysis: a second object, preview, or unused interpretation | **Comment only.** Propose cutting or moving the digression to where its object is the subject. Retain only necessary cross-references and explain the dependency. Introduction and Conclusions are exempt. | + +## Guardrails + +- **Change wording, never meaning.** Preserve definitions, theorems, claims, and field terms. Never add or remove a claim, figure, or derivation step as a language fix. +- **Recheck every number, count, and qualifier** in each rewritten sentence before continuing. +- **Comment on content changes; do not apply them.** This includes changing quantifiers or hedges, adding missing justifications, deleting paragraphs as digressions, or removing "not X but Y" contrasts. Use `[reviewer]` comments: `% [reviewer]` in LaTeX, `// [reviewer]` in Typst, or HTML comments in Markdown. The author writes the replacement. +- **Leave passing passages alone.** Every proposed rewrite names its rule; never rewrite merely to produce a diff. +- **Prose rules never require figure detail.** Conceptual and overview figures may omit implementation and timing details. Use the Figure Rulebook in `write-paper` to judge figures against their stated purpose. Flag omissions only if they materially misrepresent the central mechanism or contradict a claim attributed to the figure. Prefer clarifying labels, captions, or nearby prose; weigh added graphics against readability. Diagrams need not depict every mechanism discussed in the text. diff --git a/skills/how-to-technical-writing/checklist.md b/skills/how-to-technical-writing/checklist.md new file mode 100644 index 0000000..5eadf31 --- /dev/null +++ b/skills/how-to-technical-writing/checklist.md @@ -0,0 +1,52 @@ +# Writing checklist + +The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `write-paper` language pass or a `review-paper` writing pass. Guidelines 2, 5, and 7 apply the `write-paper` Notation and Figure Rulebooks. See `skills/write-paper/references.md` for the reasoning. Guideline numbers match `review-paper/SKILL.md`; guidelines 6, 8, and 9 are review process and live in `skills/review-paper/checklist.md`. + +--- + +## 1 — One concept per sentence + +- [ ] No sentence introduces three new ideas at once. Long compound sentences are split. +- [ ] When two concepts share a sentence, the reader already knows both. +- [ ] Actions use the active voice. Concrete verbs replace nominalizations. +- [ ] Parallel grammar appears only where the ideas already run in parallel. No prose is turned into lists. +- [ ] Sentences run about 20 words. No sentence chains clauses with semicolons or "and … so …". A sentence that wraps a display equation or binds a hypothesis to its conclusion stays whole. +- [ ] No content-free openers, "Notice that", or empty meta-talk. Signposts that name a section's job or point to a result stay. +- [ ] No "obviously" or "clearly". Each asserted step names the earlier equation, figure, or section it rests on. That reason already exists in the manuscript. +- [ ] Simple words are used and every technical word is kept. No verb, quantifier, or adjective is swapped inside a mathematical statement. No metaphor stands in for a precise statement. No finding on this rule asks a conceptual figure for more detail. +- [ ] At most one aside per paragraph. No intensifiers. Hedges of magnitude or certainty are untouched. "Not X but Y" stays where the contrast is the result. +- [ ] Runs of inline computation are moved to one display. One sentence names what the display shows. + +## 2 — Define every concept/symbol before use + +- [ ] A symbol and notation table was built while reading. +- [ ] No symbol or concept is used before it is defined. No forward references. +- [ ] No symbol is left never defined. +- [ ] Symbols are introduced in logical order. Earlier symbols define later ones. +- [ ] No symbol is reused for two meanings within a few pages. Any deliberate change is signalled with "henceforth …". + +## 3 — One job per paragraph + +- [ ] Each paragraph has one identifiable purpose. +- [ ] A topic sentence opens each paragraph. No paragraph does double duty. +- [ ] Each section delivers the mission stated for it in Phase 0. +- [ ] In Theory, Methods, Results, and Analysis, each paragraph stays on one object. No sideways digression, preview, or unused second interpretation. Introduction and Conclusions are exempt. +- [ ] Each cross-reference is needed by the current step. The sentence says why. + +## 4 — DRY / anti-repetition (new) + +- [ ] No explanation or definition is repeated across body sections. The abstract, introduction, conclusions, and main-result sentences are exempt. +- [ ] Each concept is stated once in canonical form and cross-referenced elsewhere. +- [ ] Any repetition kept for emphasis is deliberate, not accidental drift. + +## 5 — Display-math discipline + +- [ ] Display equations are reserved for flagship results, non-obvious steps, key intermediates, or equations referenced by a figure. +- [ ] Routine algebra that fits inline is not promoted to a display equation. +- [ ] No equation with a referenced label is proposed for inlining or cutting. In a letter, algebra moves to the supplement rather than losing a reproducibility step. + +## 7 — Figure integration + +- [ ] Every figure is referenced at least once in the main text. No orphan figures. +- [ ] Every striking feature, such as a peak, dip, kink, or jump, is discussed in the text. +- [ ] Captions stand alone. Every plotted quantity is defined and the trend is summarized. diff --git a/skills/review-paper/SKILL.md b/skills/review-paper/SKILL.md index 13d59f8..ec46ac3 100644 --- a/skills/review-paper/SKILL.md +++ b/skills/review-paper/SKILL.md @@ -23,7 +23,7 @@ Run a structured **review-and-enhance** pass over an *existing* scientific manus **Scope note.** This is the *reviewing/revising* counterpart to `write-paper` (which *drafts* a manuscript figures-first). It is **not** `survey` report mode, which writes technology/field-assessment reports from a literature survey. Use `review-paper` when a manuscript already exists and the user wants comments, a referee-style critique, reference/fact verification, or guideline-driven polish. If no manuscript exists yet, redirect to `write-paper`. -Guidelines 1–8 below come from a manuscript-quality rubric, and guideline 9 checks the manuscript against its target journal's own rules; the full rubric lives in `skills/review-paper/checklist.md`. Sentence- and paragraph-level rules live in the `how-to-technical-writing` skill (`skills/how-to-technical-writing/SKILL.md`); notation and figure discipline live in `write-paper/SKILL.md`. This skill **references** both rather than restating them. Consult `skills/write-paper/references.md` for the *why* behind a rule. +Guidelines 1–8 below come from a manuscript-quality rubric, and guideline 9 checks the manuscript against its target journal's own rules; the writing checklist lives in `skills/how-to-technical-writing/checklist.md` and the review-process checklist in `skills/review-paper/checklist.md`. Sentence- and paragraph-level rules live in the `how-to-technical-writing` skill (`skills/how-to-technical-writing/SKILL.md`); notation and figure discipline live in `write-paper/SKILL.md`. This skill **references** both rather than restating them. Consult `skills/write-paper/references.md` for the *why* behind a rule. Use `skills/how-to-write-ideas-report/references/writing-workflow.md` for KB/context loading, citation handling, the BibTeX lookup chain, and output mechanics. @@ -214,9 +214,9 @@ Then present a short summary to the user and ask two things: which findings to a ## Integrations - **Context, citations, output mechanics:** `skills/how-to-write-ideas-report/references/writing-workflow.md`. -- **Sentence/paragraph rules, hunt table, guardrails:** `skills/how-to-technical-writing/SKILL.md`. +- **Sentence/paragraph rules, hunt table, guardrails:** `skills/how-to-technical-writing/SKILL.md`; checkable form in `skills/how-to-technical-writing/checklist.md`. - **Rule definitions (notation/figure):** `skills/write-paper/SKILL.md` + `skills/write-paper/references.md`. - **Model paper (style calibration for fixes):** `skills/write-paper/sources/1807.01815_Ho2019_quantum-scars.md`, distilled in `skills/write-paper/references.md` §C. - **Target venue and template discussion:** `write-paper` Phase 1.5 (`skills/write-paper/SKILL.md`). - **Reference repair / adding a missing paper:** the `how-to-download-ref` skill. -- **Full rubric checklist:** `skills/review-paper/checklist.md`. +- **Review-process checklist (gate, verification, journal fit, delivery):** `skills/review-paper/checklist.md`. diff --git a/skills/review-paper/checklist.md b/skills/review-paper/checklist.md index f86812e..04bbba9 100644 --- a/skills/review-paper/checklist.md +++ b/skills/review-paper/checklist.md @@ -1,105 +1,65 @@ -# Paper-reviewer rubric +# Paper-reviewer process checklist -The nine-guideline review rubric backing `review-paper/SKILL.md`, expanded into checkable items. Use it as the per-pass checklist when reviewing a manuscript. Guidelines 1–3, 5, and 7 restate the `how-to-technical-writing` skill (`skills/how-to-technical-writing/SKILL.md`) and `write-paper` authoring rules as *review* checks — consult `skills/write-paper/references.md` for the reasoning. Guidelines 4, 6, 8, and 9 are specific to reviewing. +The review-only items behind `review-paper/SKILL.md`: the gate (6), fact and reference verification (8), journal fit (9), and delivery. The writing items (1–5, 7) live in `skills/how-to-technical-writing/checklist.md`, the single source of truth for the writing guide. --- -## 1 — One concept per sentence - -- [ ] No sentence introduces three new ideas at once; long compound sentences are split. -- [ ] Where two concepts share a sentence, both are already familiar to the reader. -- [ ] Active voice for actions; concrete verbs over nominalizations. -- [ ] Parallel grammar only where ideas already run in parallel; no prose converted into lists. -- [ ] Sentences run about 20 words; no semicolon-chained or "and … so …" triple clauses. Sentences wrapping a display equation or binding hypothesis to conclusion are left whole. -- [ ] No content-free openers, "Notice that", or empty meta-talk; signposts that name a section's job or point to a result stay. -- [ ] No "obviously" / "clearly"; each asserted step names the earlier equation, figure, or section it rests on, and that reason already exists in the manuscript. -- [ ] Plain connectives, every technical word kept; no verb, quantifier, or adjective swapped inside a mathematical statement; no metaphor standing in for a precise statement. No finding asks a conceptual figure for more detail on this rule's account. -- [ ] At most one aside per paragraph; no intensifiers; hedges of magnitude or certainty untouched; "not X but Y" kept where the contrast is the result. -- [ ] Runs of inline computation moved to one display with one sentence naming what it shows. - -## 2 — Define every concept/symbol before use - -- [ ] A symbol/notation table was built while reading. -- [ ] No symbol or concept is used before it is defined (no forward references). -- [ ] No symbol is left never-defined. -- [ ] Symbols are introduced in logical order (earlier symbols define later ones). -- [ ] No symbol is reused for two different meanings within a few pages; any deliberate change is signalled ("henceforth …"). - -## 3 — One job per paragraph - -- [ ] Each paragraph has a single, identifiable purpose. -- [ ] A topic sentence opens each paragraph; no double-duty paragraphs. -- [ ] Each section delivers the mission stated for it in Phase 0. -- [ ] In Theory, Methods, Results, and Analysis, each paragraph stays on one object; no sideways digression, preview, or unused second interpretation. Introduction and Conclusions exempt. -- [ ] Each cross-reference is needed by the current step, and the sentence says why. - -## 4 — DRY / anti-repetition (new) - -- [ ] No explanation or definition is repeated across body sections; abstract, introduction, conclusions, and main-result sentences are exempt. -- [ ] Each concept is stated canonically once and cross-referenced elsewhere. -- [ ] Repetition that *is* deliberate emphasis is intentional, not accidental drift. - -## 5 — Display-math discipline - -- [ ] Display equations are reserved for flagship results, non-obvious steps, key intermediates, or figure-referenced equations. -- [ ] Routine or inline-able algebra is not promoted to a display equation. -- [ ] No equation with a referenced label is proposed for inlining or cutting; letters move algebra to the supplement rather than deleting a reproducibility step. - ## 6 — Read the whole paper first (the gate) -- [ ] The user was asked first, with three numbered options (1 high-level story, 2 writing, 3 facts/references/links, 4 journal fit), which passes to run; on a repeat review the previous report was named and the default was option 2 only. +- [ ] The user was asked first which passes to run, with numbered options: 1 high-level story, 2 writing, 3 facts, references, and links, 4 journal fit. On a repeat review, the previous report was named and the default was option 2 only. - [ ] The whole manuscript and its bibliography were read before any critique. -- [ ] A story brief was produced: story paragraph, scientific question and its significance, numbered key contributions, key results each tied to a figure, table, or equation. +- [ ] A story brief was produced. It holds the story paragraph, the scientific question and its significance, the numbered key contributions, and the key results. Each key result is tied to a figure, table, or equation. - [ ] A one-line mission per section was produced. -- [ ] When option 1 was selected: high-level comments were made on the significance of the problem (who is blocked, what it unlocks, strongest prior attempt; `survey` suggested when the manuscript or KB cannot justify it), the significance of each contribution (stated as a verifiable property, verified by a result, better than the strongest baseline on an axis the audience names), the story (contribution matches results, gap supported), the abstract (moves mapped to the brief, unbacked or missing claims), the main figure (carries the central claim alone, or no such figure exists), the supporting data (claims without data, missing controls, baselines, error bars; evidence strong enough for the claim as worded: general claims across systems or seeds, improvements separated from baseline by error bars or a test, scaling laws over enough decades, state-of-the-art claims against the strongest baseline under the same conditions), and how the contributions are highlighted (named in the abstract, listed in the introduction, each tied to its proving figure or equation; a better main figure, summary table, title sentence, or ordering proposed when one exists). +- [ ] When option 1 was selected, high-level comments were made on each of the items below. + - The significance of the problem: who is blocked, what it unlocks, and the strongest prior attempt. `survey` is suggested when the manuscript or KB cannot justify it. + - The significance of each contribution. It is stated as a verifiable property, verified by a result, and better than the strongest baseline on an axis the audience names. + - The story. The contribution matches the results and the gap is supported. + - The abstract. Its moves are mapped to the brief. Unbacked or missing claims are named. + - The main figure. It carries the central claim alone, or no such figure exists. + - The supporting data. Claims without data, missing controls, baselines, and error bars are named. The evidence is strong enough for the claim as worded. General claims span systems or seeds. Improvements are separated from the baseline by error bars or a test. Scaling laws span enough decades. State-of-the-art claims are measured against the strongest baseline under the same conditions. + - How the contributions are highlighted. They are named in the abstract, listed in the introduction, and each tied to its proving figure or equation. A better main figure, summary table, title sentence, or ordering is proposed when one exists. - [ ] **The story brief and high-level comments were confirmed with the user before findings were generated.** -## 7 — Figure integration - -- [ ] Every figure is referenced at least once in the main text (no orphan figures). -- [ ] Every striking feature (peak, dip, kink, jump) is discussed in the text. -- [ ] Captions are self-sufficient: every plotted quantity defined, trend summarized. - ## 8 — Fact & reference verification (new) - [ ] Skipped entirely, with a note in the report, when the user did not select option 3 in Phase 0. Otherwise: -- [ ] `verify_bib.py` was run against the resolved bibliography; **every entry**, including uncited entries, appears in its report. -- [ ] Title / authors / year / venue or journal / volume / pages / DOI were screened against cached and batched Semantic Scholar metadata. -- [ ] Every `unverifiable` record and every `mismatch` with a high/medium finding was manually confirmed through CrossRef → Semantic Scholar → MCP → web fetch before reporting it; low-severity missing fields remain completion suggestions. +- [ ] `verify_bib.py` was run against the resolved bibliography. **Every entry**, including uncited entries, appears in its report. +- [ ] Title, authors, year, venue or journal, volume, pages, and DOI were screened against cached and batched Semantic Scholar metadata. +- [ ] Every `unverifiable` record was confirmed by hand before reporting. So was every `mismatch` with a high or medium finding. The chain is CrossRef → Semantic Scholar → MCP → web fetch. Low-severity missing fields remain completion suggestions. - [ ] Every `\cite` key resolves to an entry in the bibliography that was actually used. -- [ ] Broken / missing / mismatched citations flagged; repair offered via the `how-to-download-ref` skill. -- [ ] Key claims attached to a citation sanity-checked against the cited work; uncertain ones flagged, not asserted. -- [ ] Standalone checkable factual/numerical claims verified via web search; uncertain ones flagged. -- [ ] Every URL and DOI link in the manuscript and bibliography fetched once; dead links, wrong redirects, and unresolvable DOIs flagged. -- [ ] **No BibTeX invented from memory; no claim silently "corrected"; no citation fabricated.** +- [ ] Broken, missing, or mismatched citations are flagged. Repair is offered via the `how-to-download-ref` skill. +- [ ] Key claims attached to a citation are sanity-checked against the cited work. Uncertain ones are flagged, not asserted. +- [ ] Standalone checkable factual or numerical claims are verified via web search. Uncertain ones are flagged. +- [ ] Every URL and DOI link in the manuscript and bibliography is fetched once. Dead links, wrong redirects, and unresolvable DOIs are flagged. +- [ ] **No BibTeX invented from memory. No claim silently "corrected". No citation fabricated.** ## 9 — Journal fit (new) - [ ] Skipped, with a note in the report, when the user did not select option 4 or chose "no target yet". Otherwise: -- [ ] The target journal was taken from the manuscript's declared venue or `template/README.md`, or recommended per `write-paper` Phase 1.5 and confirmed by the user. -- [ ] The official author guidelines were fetched this session (or reused from `template/README.md`); source URL and access date recorded. -- [ ] Constraints extracted into a table: limits (body, abstract, title), figure / table / reference maxima, required sections and order, required statements (data and code availability, author contributions, competing interests, funding, ethics, keywords, significance), formatting rules, and the journal's own writing guidance. -- [ ] Each constraint measured against the manuscript (word counts from compiled text, counts from source, sections from headings) with status ok / over / missing / unverifiable. -- [ ] Abstract, opening paragraph, and significance framing reviewed against the journal's stated audience and writing guidance. -- [ ] **No limit or rule quoted from memory; unfetchable guidelines marked unverifiable with the URL.** +- [ ] The target journal was taken from the manuscript's declared venue or `template/README.md`. Otherwise it was recommended per `write-paper` Phase 1.5 and confirmed by the user. +- [ ] The official author guidelines were fetched this session or reused from `template/README.md`. The source URL and access date are recorded. +- [ ] Constraints were extracted into a table. It covers limits on body, abstract, and title, the figure, table, and reference maxima, the required sections and their order, the required statements, the formatting rules, and the journal's own writing guidance. Required statements include data and code availability, author contributions, competing interests, funding, ethics, keywords, and significance. +- [ ] Each constraint was measured against the manuscript. Word counts come from compiled text, counts from source, and sections from headings. Each has a status of ok, over, missing, or unverifiable. +- [ ] The abstract, opening paragraph, and significance framing were reviewed against the journal's stated audience and writing guidance. +- [ ] **No limit or rule is quoted from memory. Unfetchable guidelines are marked unverifiable with the URL.** --- ## Language-pass hunt table (guidelines 1, 3, 4, 5) -The hunt-for / fix table lives in `skills/how-to-technical-writing/SKILL.md`, shared with `write-paper`. Each finding cites its row. Rows marked **comment only** are never applied as edits, even after approval. +The checkable items live in `skills/how-to-technical-writing/checklist.md`. The hunt-for / fix table lives in `skills/how-to-technical-writing/SKILL.md`, shared with `write-paper`. Each finding cites its row. Rows marked **comment only** are never applied as edits, even after approval. ## Delivery & application -- [ ] Findings written to `articles//review-YYYY-MM-DD.md`, grouped by guideline and severity-ranked. -- [ ] A reference/fact-check table (cite key → status → note) is included. -- [ ] A journal fit table (constraint → required → measured → status) with the guideline source is included, or a line saying the pass was skipped. +- [ ] Findings are written to `articles//review-YYYY-MM-DD.md`, grouped by guideline and ranked by severity. +- [ ] A reference and fact-check table (cite key → status → note) is included. +- [ ] A journal fit table (constraint → required → measured → status) with the guideline source is included. Otherwise a line says the pass was skipped. - [ ] A prioritized "top fixes" list is included. -- [ ] The user was asked whether to see a marked diff first or apply directly; marked diff is the default. -- [ ] In marked-diff mode: edits went to a `*.proposed.*` copy, `latexdiff` (or `git diff --word-diff` for Typst/Markdown) produced the marked version, a numbered legend was handed over, and only the accepted numbers were merged; proposed and diff files deleted afterwards. -- [ ] Edits applied only after user approval (all / by-severity / individual). -- [ ] LaTeX/Typst/Markdown structure and macros preserved; author-judgment fixes left as `% [reviewer]` comments. -- [ ] Language edits changed how sentences are written, never what they say; no definition, theorem, claim, or field term altered; numbers and qualifiers rechecked after every rewrite. +- [ ] The user was asked whether to see a marked diff first or apply directly. The marked diff is the default. +- [ ] In marked-diff mode, edits went to a `*.proposed.*` copy. `latexdiff` produced the marked version, or `git diff --word-diff` for Typst and Markdown. A numbered legend was handed over. Only the accepted numbers were merged. The proposed and diff files were deleted afterwards. +- [ ] Edits were applied only after user approval, either all, by severity, or one by one. +- [ ] LaTeX, Typst, and Markdown structure and macros are preserved. Author-judgment fixes are left as `% [reviewer]` comments. +- [ ] Language edits changed how sentences are written, never what they say. No definition, theorem, claim, or field term was altered. Numbers and qualifiers were rechecked after every rewrite. - [ ] Fixes touching a quantifier, hedge, missing justification, paragraph deletion, or "not X but Y" contrast were left as `[reviewer]` comments, not applied. -- [ ] Manuscript re-compiled (`latexmk` / `pdflatex` / `typst compile`) and the result reported. -- [ ] A changelog appended to the top of the review report. +- [ ] The manuscript was re-compiled with `latexmk`, `pdflatex`, or `typst compile`, and the result was reported. +- [ ] A changelog was appended to the top of the review report. diff --git a/skills/write-paper/SKILL.md b/skills/write-paper/SKILL.md index 4caf4e8..7021ecd 100644 --- a/skills/write-paper/SKILL.md +++ b/skills/write-paper/SKILL.md @@ -188,7 +188,7 @@ Notation is the reader's interface to the math. Treat it with the same care as a ## Sentence-Level Rules -Follow `skills/how-to-technical-writing/SKILL.md`: one concept per sentence, direct to the point, name the earlier context instead of "obviously", plain connectives with every technical word kept, no undrawn metaphors, active voice, one aside per paragraph, calculations in displays, locality within body sections, say it once within the body, signposting, and one job per paragraph. The guide's hunt table is the checklist for the Phase 4 language pass, and its guardrails say which fixes are never applied mechanically. +Follow `skills/how-to-technical-writing/SKILL.md`: one concept per sentence, direct to the point, name the earlier context instead of "obviously", simple words with every technical word kept, no undrawn metaphors, active voice, one aside per paragraph, calculations in displays, locality within body sections, say it once within the body, signposting, and one job per paragraph. The guide's `checklist.md` and hunt table are the checklist for the Phase 4 language pass, and its guardrails say which fixes are never applied mechanically. --- From 940262a86f6ebeb42f458d26db04560e38fd9671 Mon Sep 17 00:00:00 2001 From: GiggleLiu Date: Thu, 10 Sep 2026 20:23:04 +0800 Subject: [PATCH 2/7] how-to-technical-writing: seven rules borrowed from the learning-sheet skills Delete test, trust the structure, define at the point of need, pointer not restatement, pay every promise, no drifting duplicates, and set up before calculating. Each has a hunt row and a checklist item. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_018cc6n2NyTUNUDQ7LhzZDur --- skills/how-to-technical-writing/SKILL.md | 13 ++++++++++++- skills/how-to-technical-writing/checklist.md | 7 +++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/skills/how-to-technical-writing/SKILL.md b/skills/how-to-technical-writing/SKILL.md index 3c22287..c263ec7 100644 --- a/skills/how-to-technical-writing/SKILL.md +++ b/skills/how-to-technical-writing/SKILL.md @@ -33,9 +33,14 @@ Clarity outranks these rules. When they conflict, keep the clearer sentence. ### Conceptual clarity and semantic coherence - **Explain concepts with existing concepts.** Do not use concepts never explained, or that are not a common sense to explain a new idea. +- **Define at the point of need.** Introduce a term or symbol only when the argument needs it. Every definition is used later in the paper. +- **Set up before calculating.** Before a derivation, state the system, the assumptions or boundary conditions, the symbols, and the quantity being computed. Use a labelled setup figure when geometry matters. - **One job per paragraph.** Each paragraph has its own mission. Start with a topic sentence, support it with detail, and end with a transition or emphasis. Do not mix different jobs in the same paragraph. - **Locality rule.** Keep each paragraph on one object and each section on its job. Avoid connecting to concepts not within current scope, previewing later sections, or adding unused interpretations. Keep cross-references only when the current step depends on them, and say why: "by the linearity of Eq. (3)". In paper writing, abstracts, introduction, and conclusions are exempt. -- **Do not repeat yourself.** Cut sentences that do not carry new information or new examples. +- **Do not repeat yourself.** Cut sentences that do not carry new information or new examples. A second appearance of a fact is a pointer, never a restatement. A number, count, or list stated in two places can drift, so state it once and point to it. +- **The delete test.** A sentence stays only if removing it leaves a gap that something later in the section depends on. Run the test against the whole section, not the next sentence, so a setup for a later payoff survives. +- **Trust the structure.** Do not re-describe in words what an equation, table, or figure already shows. At most one clause points at what to look at. The text says what a feature means, not what shape it has. +- **Pay every promise.** Every "we will show", "surprisingly", or "the key link" has a later line that pays it with a result, theorem, or figure. A promise paid only by a hint is cut or paid. ### Narrative and wording choices @@ -57,10 +62,16 @@ Use for reviews and final language passes. Each finding cites its row; leave pas |---|---| | An overloaded sentence or stacked clauses | Split, retaining logical links such as "so" or "because". Use length as a review signal, not a target. Keep sentences wrapping display equations or binding hypotheses to conclusions whole. | | Restatement of the main-result sentence, equation, or paragraph opening | Delete the restatement; keep the canonical statement. | +| A sentence whose removal leaves no gap anywhere later in the section | Delete it, or fold its one useful clause into a neighbour. Test against the whole section. | +| Prose that re-describes what a nearby equation, table, or figure shows | Cut it to one clause pointing at what to look at. Keep the sentence that says what the feature means. | +| A promise ("we will show", "surprisingly", "the key link") with no line that pays it | **Comment only.** Name the promise and ask for the payoff or the cut. | +| A term or symbol defined before the argument needs it, or never used after its definition | **Comment only.** Propose moving the definition to its first use, or cutting it. | +| A number, count, or list stated in two places | Keep one statement and point to it from the other. Abstract and conclusions are exempt. | | "Notice that", "As one can see", "It is worth noting" | State the fact directly. | | Metaphor or idiom: "in disguise", "clue", "recipe", "cashes in" | Use plain wording with identical meaning: "in different notation", "start from", "formula". Keep field idioms such as "the gap survives disorder". | | Fancy words where simple ones explain the idea: "hence", "thus", "likewise", "utilize", "demonstrate", "commence" | Use "so", "also", "use", "show", "start". Preserve mathematical verbs, quantifiers, and adjectives as required by the technical-words rule. | | Wrong count or qualifier, such as "three approximations" when there are four | Correct it or drop the number. | +| A derivation that starts before the system, assumptions, symbols, and target quantity are stated | **Comment only.** Ask for the setup, and a labelled figure when geometry matters. | | "Always", "only", "never" contradicted later | Qualify or cut the claim. | | Two or more inline computations in a paragraph | Combine into one display and one explanatory sentence. Cut algebra that earns no display, subject to the equation and derivation guardrails. | | Multiple asides in a paragraph, intensifiers, or empty evaluatives | Cut the aside or make it a sentence; delete intensifiers. Preserve magnitude and certainty hedges listed above. | diff --git a/skills/how-to-technical-writing/checklist.md b/skills/how-to-technical-writing/checklist.md index 5eadf31..73a8384 100644 --- a/skills/how-to-technical-writing/checklist.md +++ b/skills/how-to-technical-writing/checklist.md @@ -16,12 +16,16 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr - [ ] Simple words are used and every technical word is kept. No verb, quantifier, or adjective is swapped inside a mathematical statement. No metaphor stands in for a precise statement. No finding on this rule asks a conceptual figure for more detail. - [ ] At most one aside per paragraph. No intensifiers. Hedges of magnitude or certainty are untouched. "Not X but Y" stays where the contrast is the result. - [ ] Runs of inline computation are moved to one display. One sentence names what the display shows. +- [ ] No sentence re-describes what a nearby equation, table, or figure shows. At most one clause points at it. +- [ ] Every promise ("we will show", "surprisingly", "the key link") is paid by a later result, theorem, or figure. ## 2 — Define every concept/symbol before use - [ ] A symbol and notation table was built while reading. - [ ] No symbol or concept is used before it is defined. No forward references. - [ ] No symbol is left never defined. +- [ ] No term or symbol is defined before the argument needs it. Every definition is used later. +- [ ] Each derivation is preceded by the system, the assumptions or boundary conditions, the symbols, and the quantity being computed. - [ ] Symbols are introduced in logical order. Earlier symbols define later ones. - [ ] No symbol is reused for two meanings within a few pages. Any deliberate change is signalled with "henceforth …". @@ -38,6 +42,9 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr - [ ] No explanation or definition is repeated across body sections. The abstract, introduction, conclusions, and main-result sentences are exempt. - [ ] Each concept is stated once in canonical form and cross-referenced elsewhere. - [ ] Any repetition kept for emphasis is deliberate, not accidental drift. +- [ ] A second appearance of a fact is a pointer, never a restatement. +- [ ] No number, count, or list is stated in two places that can drift. Abstract and conclusions are exempt. +- [ ] Every sentence passes the delete test: removing it leaves a gap something later in the section depends on. ## 5 — Display-math discipline From 0ca9c109da86e455229c0ad090f8070c7404479a Mon Sep 17 00:00:00 2001 From: GiggleLiu Date: Thu, 10 Sep 2026 20:28:11 +0800 Subject: [PATCH 3/7] how-to-technical-writing: never address the reader as you Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_018cc6n2NyTUNUDQ7LhzZDur --- skills/how-to-technical-writing/SKILL.md | 2 ++ skills/how-to-technical-writing/checklist.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/skills/how-to-technical-writing/SKILL.md b/skills/how-to-technical-writing/SKILL.md index c263ec7..1aa820b 100644 --- a/skills/how-to-technical-writing/SKILL.md +++ b/skills/how-to-technical-writing/SKILL.md @@ -49,6 +49,7 @@ Clarity outranks these rules. When they conflict, keep the clearer sentence. - **Simple words; preserve technical words.** Explain ideas with simple words rather than fancy ones. Prefer "so" to "hence" or "thus", "also" to "likewise", "use" to "utilize", "show" to "demonstrate", and "start" to "commence". Replace only everyday words, connectives, and filler without mathematical meaning. Never replace verbs, quantifiers, or adjectives in mathematical statements, including "arbitrary", "determined by", "identify with", and "the converse". Keep field terms such as "decoherence", "ansatz", and "thermalize". Textbook and referee vocabulary stays. - **No metaphor.** - **Active voice for actions.** Prefer "We measured" to "measurements were performed." Reserve passive for things without an agent. Put the verb early with a concrete subject. +- **Never address the reader.** No "you" in a paper. State the fact, or say what the authors do. - **Concrete verbs over nominalizations.** Prefer "We adopt the new notation" to "Adoption of the new notation is undertaken." - **Prose carries ideas; calculations go to displays.** Body sentences state ideas, intuitions, or logical steps. Combine two or more inline computations in a paragraph into one display, followed by one sentence explaining it. - **Parallel grammar for parallel ideas.** Give comparisons, contrasts, and existing list items the same grammatical shape. Preserve prose layout; do not turn paragraphs into bullets or add lists a journal would not print. Papers develop arguments, and lists interrupt their flow. @@ -68,6 +69,7 @@ Use for reviews and final language passes. Each finding cites its row; leave pas | A term or symbol defined before the argument needs it, or never used after its definition | **Comment only.** Propose moving the definition to its first use, or cutting it. | | A number, count, or list stated in two places | Keep one statement and point to it from the other. Abstract and conclusions are exempt. | | "Notice that", "As one can see", "It is worth noting" | State the fact directly. | +| "You" addressing the reader | State the fact, or say what the authors do. | | Metaphor or idiom: "in disguise", "clue", "recipe", "cashes in" | Use plain wording with identical meaning: "in different notation", "start from", "formula". Keep field idioms such as "the gap survives disorder". | | Fancy words where simple ones explain the idea: "hence", "thus", "likewise", "utilize", "demonstrate", "commence" | Use "so", "also", "use", "show", "start". Preserve mathematical verbs, quantifiers, and adjectives as required by the technical-words rule. | | Wrong count or qualifier, such as "three approximations" when there are four | Correct it or drop the number. | diff --git a/skills/how-to-technical-writing/checklist.md b/skills/how-to-technical-writing/checklist.md index 73a8384..58bb95c 100644 --- a/skills/how-to-technical-writing/checklist.md +++ b/skills/how-to-technical-writing/checklist.md @@ -8,7 +8,7 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr - [ ] No sentence introduces three new ideas at once. Long compound sentences are split. - [ ] When two concepts share a sentence, the reader already knows both. -- [ ] Actions use the active voice. Concrete verbs replace nominalizations. +- [ ] Actions use the active voice. Concrete verbs replace nominalizations. The reader is never addressed as "you". - [ ] Parallel grammar appears only where the ideas already run in parallel. No prose is turned into lists. - [ ] Sentences run about 20 words. No sentence chains clauses with semicolons or "and … so …". A sentence that wraps a display equation or binds a hypothesis to its conclusion stays whole. - [ ] No content-free openers, "Notice that", or empty meta-talk. Signposts that name a section's job or point to a result stay. From af13ec0be339662656f50d905065479c5a8f9747 Mon Sep 17 00:00:00 2001 From: GiggleLiu Date: Thu, 10 Sep 2026 20:30:31 +0800 Subject: [PATCH 4/7] Revert "how-to-technical-writing: never address the reader as you" This reverts commit 0ca9c109da86e455229c0ad090f8070c7404479a. --- skills/how-to-technical-writing/SKILL.md | 2 -- skills/how-to-technical-writing/checklist.md | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/skills/how-to-technical-writing/SKILL.md b/skills/how-to-technical-writing/SKILL.md index 1aa820b..c263ec7 100644 --- a/skills/how-to-technical-writing/SKILL.md +++ b/skills/how-to-technical-writing/SKILL.md @@ -49,7 +49,6 @@ Clarity outranks these rules. When they conflict, keep the clearer sentence. - **Simple words; preserve technical words.** Explain ideas with simple words rather than fancy ones. Prefer "so" to "hence" or "thus", "also" to "likewise", "use" to "utilize", "show" to "demonstrate", and "start" to "commence". Replace only everyday words, connectives, and filler without mathematical meaning. Never replace verbs, quantifiers, or adjectives in mathematical statements, including "arbitrary", "determined by", "identify with", and "the converse". Keep field terms such as "decoherence", "ansatz", and "thermalize". Textbook and referee vocabulary stays. - **No metaphor.** - **Active voice for actions.** Prefer "We measured" to "measurements were performed." Reserve passive for things without an agent. Put the verb early with a concrete subject. -- **Never address the reader.** No "you" in a paper. State the fact, or say what the authors do. - **Concrete verbs over nominalizations.** Prefer "We adopt the new notation" to "Adoption of the new notation is undertaken." - **Prose carries ideas; calculations go to displays.** Body sentences state ideas, intuitions, or logical steps. Combine two or more inline computations in a paragraph into one display, followed by one sentence explaining it. - **Parallel grammar for parallel ideas.** Give comparisons, contrasts, and existing list items the same grammatical shape. Preserve prose layout; do not turn paragraphs into bullets or add lists a journal would not print. Papers develop arguments, and lists interrupt their flow. @@ -69,7 +68,6 @@ Use for reviews and final language passes. Each finding cites its row; leave pas | A term or symbol defined before the argument needs it, or never used after its definition | **Comment only.** Propose moving the definition to its first use, or cutting it. | | A number, count, or list stated in two places | Keep one statement and point to it from the other. Abstract and conclusions are exempt. | | "Notice that", "As one can see", "It is worth noting" | State the fact directly. | -| "You" addressing the reader | State the fact, or say what the authors do. | | Metaphor or idiom: "in disguise", "clue", "recipe", "cashes in" | Use plain wording with identical meaning: "in different notation", "start from", "formula". Keep field idioms such as "the gap survives disorder". | | Fancy words where simple ones explain the idea: "hence", "thus", "likewise", "utilize", "demonstrate", "commence" | Use "so", "also", "use", "show", "start". Preserve mathematical verbs, quantifiers, and adjectives as required by the technical-words rule. | | Wrong count or qualifier, such as "three approximations" when there are four | Correct it or drop the number. | diff --git a/skills/how-to-technical-writing/checklist.md b/skills/how-to-technical-writing/checklist.md index 58bb95c..73a8384 100644 --- a/skills/how-to-technical-writing/checklist.md +++ b/skills/how-to-technical-writing/checklist.md @@ -8,7 +8,7 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr - [ ] No sentence introduces three new ideas at once. Long compound sentences are split. - [ ] When two concepts share a sentence, the reader already knows both. -- [ ] Actions use the active voice. Concrete verbs replace nominalizations. The reader is never addressed as "you". +- [ ] Actions use the active voice. Concrete verbs replace nominalizations. - [ ] Parallel grammar appears only where the ideas already run in parallel. No prose is turned into lists. - [ ] Sentences run about 20 words. No sentence chains clauses with semicolons or "and … so …". A sentence that wraps a display equation or binds a hypothesis to its conclusion stays whole. - [ ] No content-free openers, "Notice that", or empty meta-talk. Signposts that name a section's job or point to a result stay. From e91ddf978a0f18f5771045118e0e192f0c5de87f Mon Sep 17 00:00:00 2001 From: Xiwei Pan Date: Fri, 11 Sep 2026 17:08:28 +0800 Subject: [PATCH 5/7] update checklist --- skills/how-to-technical-writing/checklist.md | 62 ++++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/skills/how-to-technical-writing/checklist.md b/skills/how-to-technical-writing/checklist.md index 73a8384..20e14c1 100644 --- a/skills/how-to-technical-writing/checklist.md +++ b/skills/how-to-technical-writing/checklist.md @@ -1,59 +1,59 @@ # Writing checklist -The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `write-paper` language pass or a `review-paper` writing pass. Guidelines 2, 5, and 7 apply the `write-paper` Notation and Figure Rulebooks. See `skills/write-paper/references.md` for the reasoning. Guideline numbers match `review-paper/SKILL.md`; guidelines 6, 8, and 9 are review process and live in `skills/review-paper/checklist.md`. +The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `write-paper` language pass or a `review-paper` writing pass. The five sections below group items by topic; their numbers are not the guideline numbers in `review-paper/SKILL.md`. Sentence structure and wording cover guideline 1; paragraph focus and information flow bring together items from guidelines 1, 3, and 4; definitions and notation cover guideline 2; equations and figures bring together items from guidelines 1, 5, and 7. Guidelines 2, 5, and 7 apply the `write-paper` Notation and Figure Rulebooks. See `skills/write-paper/references.md` for the reasoning. Guidelines 6, 8, and 9 are review process and live in `skills/review-paper/checklist.md`. --- -## 1 — One concept per sentence +## 1 — Sentence structure -- [ ] No sentence introduces three new ideas at once. Long compound sentences are split. +- [ ] No sentence introduces multiple new ideas at once. Long compound sentences are split. - [ ] When two concepts share a sentence, the reader already knows both. -- [ ] Actions use the active voice. Concrete verbs replace nominalizations. - [ ] Parallel grammar appears only where the ideas already run in parallel. No prose is turned into lists. -- [ ] Sentences run about 20 words. No sentence chains clauses with semicolons or "and … so …". A sentence that wraps a display equation or binds a hypothesis to its conclusion stays whole. -- [ ] No content-free openers, "Notice that", or empty meta-talk. Signposts that name a section's job or point to a result stay. -- [ ] No "obviously" or "clearly". Each asserted step names the earlier equation, figure, or section it rests on. That reason already exists in the manuscript. -- [ ] Simple words are used and every technical word is kept. No verb, quantifier, or adjective is swapped inside a mathematical statement. No metaphor stands in for a precise statement. No finding on this rule asks a conceptual figure for more detail. -- [ ] At most one aside per paragraph. No intensifiers. Hedges of magnitude or certainty are untouched. "Not X but Y" stays where the contrast is the result. -- [ ] Runs of inline computation are moved to one display. One sentence names what the display shows. -- [ ] No sentence re-describes what a nearby equation, table, or figure shows. At most one clause points at it. -- [ ] Every promise ("we will show", "surprisingly", "the key link") is paid by a later result, theorem, or figure. +- [ ] Sentences run about 20 words. No semicolon chains, “and … so …” chains, paired em-dash asides, or paired-comma appositives. +- [ ] A sentence that wraps a display equation or binds a hypothesis to its conclusion stays whole. -## 2 — Define every concept/symbol before use +## 2 — Wording and tone -- [ ] A symbol and notation table was built while reading. -- [ ] No symbol or concept is used before it is defined. No forward references. -- [ ] No symbol is left never defined. -- [ ] No term or symbol is defined before the argument needs it. Every definition is used later. -- [ ] Each derivation is preceded by the system, the assumptions or boundary conditions, the symbols, and the quantity being computed. -- [ ] Symbols are introduced in logical order. Earlier symbols define later ones. -- [ ] No symbol is reused for two meanings within a few pages. Any deliberate change is signalled with "henceforth …". +- [ ] Prefer active voice. Concrete verbs replace nominalizations. +- [ ] No content-free openers, "Notice that", or empty meta-talk. Signposts that name a section's job or point to a result stay. +- [ ] Simple words are used and every technical word is kept. No verb, quantifier, or adjective is swapped inside a mathematical statement. +- [ ] No metaphor. +- [ ] Avoid “X, not Y”. State X directly. +- [ ] Replace vague abstract nouns (“property,” “system,” “structure,” ...) with the specific concept they refer to. +- [ ] Use literal verbs. Do not use metaphorical verbs (“unlock”, “bridge”, "open", ...). -## 3 — One job per paragraph +## 3 — Paragraph focus and information flow - [ ] Each paragraph has one identifiable purpose. - [ ] A topic sentence opens each paragraph. No paragraph does double duty. -- [ ] Each section delivers the mission stated for it in Phase 0. - [ ] In Theory, Methods, Results, and Analysis, each paragraph stays on one object. No sideways digression, preview, or unused second interpretation. Introduction and Conclusions are exempt. -- [ ] Each cross-reference is needed by the current step. The sentence says why. - -## 4 — DRY / anti-repetition (new) - +- [ ] Use a cross-reference only when it supports the sentence. Explain the connection. +- [ ] No "obviously" or "clearly". Each asserted step names the earlier equation, figure, or section it rests on. That reason already exists in the manuscript. +- [ ] At most one aside per paragraph. No rhetorical intensifiers. Hedges of magnitude or certainty are untouched. - [ ] No explanation or definition is repeated across body sections. The abstract, introduction, conclusions, and main-result sentences are exempt. - [ ] Each concept is stated once in canonical form and cross-referenced elsewhere. - [ ] Any repetition kept for emphasis is deliberate, not accidental drift. - [ ] A second appearance of a fact is a pointer, never a restatement. - [ ] No number, count, or list is stated in two places that can drift. Abstract and conclusions are exempt. +- [ ] Do not repeat information already visible in a nearby equation, table, or figure. State the relevant conclusion or implication. - [ ] Every sentence passes the delete test: removing it leaves a gap something later in the section depends on. -## 5 — Display-math discipline +## 4 — Definitions and notation + +- [ ] A symbol and notation table was built while reading. +- [ ] No symbol or concept is used before it is defined. No forward references. +- [ ] No symbol is left never defined. +- [ ] No term or symbol is defined before the argument needs it. Every definition is used later. +- [ ] State the assumptions, define the symbols, and identify the target before a derivation. +- [ ] Symbols are introduced in logical order. Earlier symbols define later ones. +- [ ] Do not reuse a symbol for a different meaning in the same section or argument. + +## 5 — Equations and figures +- [ ] Do not use inline calculations. Use a display instead. - [ ] Display equations are reserved for flagship results, non-obvious steps, key intermediates, or equations referenced by a figure. - [ ] Routine algebra that fits inline is not promoted to a display equation. - [ ] No equation with a referenced label is proposed for inlining or cutting. In a letter, algebra moves to the supplement rather than losing a reproducibility step. - -## 7 — Figure integration - - [ ] Every figure is referenced at least once in the main text. No orphan figures. - [ ] Every striking feature, such as a peak, dip, kink, or jump, is discussed in the text. -- [ ] Captions stand alone. Every plotted quantity is defined and the trend is summarized. +- [ ] Captions stand alone but stay concise. Every plotted quantity is defined and the trend is summarized. Keep experimental settings and procedural details in the main text. From 48349399cdc687c0e179442e3e3a79e72e640272 Mon Sep 17 00:00:00 2001 From: Jinguo Liu Date: Sat, 12 Sep 2026 09:59:22 +0800 Subject: [PATCH 6/7] Update skills/how-to-technical-writing/checklist.md --- skills/how-to-technical-writing/checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/how-to-technical-writing/checklist.md b/skills/how-to-technical-writing/checklist.md index 20e14c1..870bb95 100644 --- a/skills/how-to-technical-writing/checklist.md +++ b/skills/how-to-technical-writing/checklist.md @@ -7,7 +7,7 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr ## 1 — Sentence structure - [ ] No sentence introduces multiple new ideas at once. Long compound sentences are split. -- [ ] When two concepts share a sentence, the reader already knows both. +- [ ] Do not use concepts that target reader are not familiar with to explaining a concept - [ ] Parallel grammar appears only where the ideas already run in parallel. No prose is turned into lists. - [ ] Sentences run about 20 words. No semicolon chains, “and … so …” chains, paired em-dash asides, or paired-comma appositives. - [ ] A sentence that wraps a display equation or binds a hypothesis to its conclusion stays whole. From c5ef50cc843eaed80561f6533b9575cd78dcec71 Mon Sep 17 00:00:00 2001 From: Jinguo Liu Date: Sat, 12 Sep 2026 09:59:28 +0800 Subject: [PATCH 7/7] Update skills/how-to-technical-writing/checklist.md --- skills/how-to-technical-writing/checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/how-to-technical-writing/checklist.md b/skills/how-to-technical-writing/checklist.md index 870bb95..edd127d 100644 --- a/skills/how-to-technical-writing/checklist.md +++ b/skills/how-to-technical-writing/checklist.md @@ -9,7 +9,7 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr - [ ] No sentence introduces multiple new ideas at once. Long compound sentences are split. - [ ] Do not use concepts that target reader are not familiar with to explaining a concept - [ ] Parallel grammar appears only where the ideas already run in parallel. No prose is turned into lists. -- [ ] Sentences run about 20 words. No semicolon chains, “and … so …” chains, paired em-dash asides, or paired-comma appositives. +- [ ] Sentences run about 8-25 words. No semicolon chains, “and … so …” chains, paired em-dash asides, or paired-comma appositives. - [ ] A sentence that wraps a display equation or binds a hypothesis to its conclusion stays whole. ## 2 — Wording and tone