From 1fea124ee75d4bda75026909f9e8927bf02f47a8 Mon Sep 17 00:00:00 2001 From: nzy1997 Date: Mon, 21 Sep 2026 09:32:28 +0800 Subject: [PATCH] Preserve author control through manuscript workflows --- skills/how-to-review-figure/SKILL.md | 30 +-- skills/review-paper/SKILL.md | 149 +++++++---- skills/review-paper/checklist.md | 36 +-- skills/write-paper/SKILL.md | 243 ++++++++---------- .../references/figures-and-notation.md | 50 ++++ tests/test_write_paper_resources.py | 29 +++ 6 files changed, 318 insertions(+), 219 deletions(-) create mode 100644 skills/write-paper/references/figures-and-notation.md create mode 100644 tests/test_write_paper_resources.py diff --git a/skills/how-to-review-figure/SKILL.md b/skills/how-to-review-figure/SKILL.md index ee8bc4f..3d2d5e5 100644 --- a/skills/how-to-review-figure/SKILL.md +++ b/skills/how-to-review-figure/SKILL.md @@ -5,14 +5,11 @@ description: Agentic trigger. Use when judging the visual design of a figure, pl ## 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` to its +real path before locating bundled resources. `skills//...` refers to the +installed skill found by public name, not the user's project; dependencies need +not be siblings. Load only resources needed for the current task. If a required +dependency is missing, report it before that dependent step. Before running the examples, set `REVIEW_FIGURE_DIR` to the absolute directory of `how-to-review-figure`. Quote these variables as shown. @@ -29,10 +26,13 @@ The full rubric — each rule's "good looks like" and "flag when" — lives in ` ## Operating principle -**Source-aware, report-only, terminal-first.** +**Source-aware, scoped to the request, terminal-first.** - **Source-aware** — always look at a rendered raster before scoring (never judge a figure you have not seen); when source exists, read it too so a fix can cite a line or parameter. -- **Report-only** — never edit the figure or its source. Suggest concrete changes; the user applies them. +- **Review scope** — a review-only request produces findings. When called inside + an authorized figure/deck creation or repair task, return actionable findings + to the authoring workflow, which applies fixes and rechecks affected figures. + A standalone request that also asks for fixes authorizes those source edits. - **Terminal-first** — print the scorecard to the chat by default. Write a file only when the user asks. --- @@ -77,7 +77,7 @@ Rank every non-pass finding so the user can triage: ## Phase 0 — Scope & render 1. **Resolve target(s).** Accept explicit path(s), a directory, or auto-detect (`images/`, `figures/`, then `*.png|jpg|jpeg|pdf|svg|typ` in the working directory). If several are found and the user did not name one, list them and ask which to review. -2. **Establish the display context.** Ask once (with a default): where will this figure appear — **paper single-column / paper double-column / slide / poster / web** — and the final width. This is what makes S1 (text size) and S9 (resolution) meaningful. **Default if unspecified:** paper double-column (~3.4 in wide). +2. **Establish the display context.** Reuse the paper, slide, poster, or web dimensions from the request or caller. If unknown, state a provisional display size and qualify size-dependent findings; ask only when intended dimensions are necessary to resolve them. 3. **Render to a raster you can look at (source-aware).** Use the helper: ```bash @@ -87,7 +87,7 @@ Rank every non-pass finding so the user can triage: - raster (`.png`/`.jpg`) and `.pdf` → read directly (the helper passes them through). - `.typ` → compiled to PNG via `typst`. - `.svg` → converted to PNG via the first available of `rsvg-convert` / `inkscape` / `cairosvg`. - - matplotlib `.py` → rendered **only** with `--allow-exec` (open figures captured to PNG). Confirm with the user before passing `--allow-exec`; otherwise prefer an already-rendered output, or ask for a PNG. + - matplotlib `.py` → rendered **only** with `--allow-exec` (open figures captured to PNG). Inspect the script and reuse authorization to run the project's plotting code. If execution is outside that scope or has unclear side effects, use an existing render or ask before passing `--allow-exec`. - The helper prints the viewable PNG path(s) to stdout. If it fails (no renderer available), **ask the user to export a PNG** — do not score an unseen figure. Then **read the produced raster** with your image-reading ability. When the source exists, also read it as text so fixes can cite a line/parameter. @@ -127,7 +127,7 @@ Print, per figure: For a multi-figure run, add a brief cross-figure summary (shared problems, inconsistencies across the set). -Then **offer to save**: only on a yes, write `figure-review-YYYY-MM-DD.md` beside the reviewed figure(s) (or a path the user gives), using the same structure. This matches the repo's dated-output convention (cf. `review-paper`). +When the user requested a saved report, write `figure-review-YYYY-MM-DD.md` beside the reviewed figure(s) (or a path the user gives), using the same structure. This matches the repo's dated-output convention (cf. `review-paper`). --- @@ -146,8 +146,8 @@ Then **offer to save**: only on a yes, write `figure-review-YYYY-MM-DD.md` besid | Scoring a figure you never rendered | Phase 0 step 3: render and look first; ask for a PNG if rendering fails. | | Judging "text too small" with no context | Phase 0 step 2 fixes the intended display size before S1/S9. | | Applying scientific rules to a schematic | Classify first; S-rules add on only for plots. | -| Editing the figure or its source | Report-only — suggest, never apply. | -| Running a matplotlib `.py` silently | Render `.py` only with `--allow-exec` after user confirmation; else use existing output or ask for a PNG. | +| Editing the figure or its source | Review-only — suggest changes; apply only when figure fixes are already requested. | +| Running a matplotlib `.py` silently | Inspect the script and execute within existing authorization; otherwise use existing output or ask. | | Asserting a subjective taste call as fact | Mark subjective findings as opinion; ground the rest in the raster/source. | --- diff --git a/skills/review-paper/SKILL.md b/skills/review-paper/SKILL.md index ec46ac3..a939626 100644 --- a/skills/review-paper/SKILL.md +++ b/skills/review-paper/SKILL.md @@ -5,21 +5,18 @@ description: User trigger. Use when reviewing, commenting on, or fact-checking a ## 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` to its +real path before locating bundled resources. `skills//...` refers to the +installed skill found by public name, not the user's project; dependencies need +not be siblings. Load only resources needed for the current task. If a required +dependency is missing, report it before that dependent step. Before running the examples, set `DOWNLOAD_REF_DIR` to the absolute directory of `how-to-download-ref`. Quote these variables as shown. # Paper Reviewer -Run a structured **review-and-enhance** pass over an *existing* scientific manuscript. The skill reads the whole paper, produces **location-anchored comments first**, then applies only the edits the user approves and re-checks that the manuscript still compiles. +Run a structured **review-and-enhance** pass over an *existing* scientific manuscript. The skill reads the context needed for the selected scope, delivers **location-anchored findings**, and applies requested edits with appropriate verification. **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`. @@ -31,7 +28,24 @@ Use `skills/how-to-write-ideas-report/references/writing-workflow.md` for KB/con ## Operating principle -**Comment-first, non-destructive.** Never edit the manuscript before the user has seen and approved the findings. Read the whole paper, deliver the comments, let the user choose what to apply, *then* edit. This mirrors `write-paper`'s "iterate the story with the user" philosophy: the author keeps control of judgment calls. +**Choose the application mode before changing a manuscript file.** Use the +user's current instructions and prior decisions: + +| Request or existing decision | Application mode | +|---|---| +| Review, critique, comments, or fact check | Findings only; leave the original unchanged. | +| Polish or revise a whole manuscript, with no direct-edit decision | Marked proposal in a separate copy; leave the original unchanged until the user accepts changes. | +| Explicitly edit the original directly, apply accepted findings, or continue an established direct-edit mode | Apply within that authorization and verify; do not ask again. | +| A specific local replacement or edit to a named passage | Complete that local edit without reopening whole-paper approval. | +| Rewrite an excerpt supplied in chat | Return revised text inline. | + +Naming `main.md` or limiting a whole-paper polish to English/grammar does not +select direct mode. Prepare the marked proposal and numbered changes before +asking which to apply; do not ask permission to begin the work. A user-requested +preview takes precedence over the local-edit default. For wording-only work, +preserve scientific meaning. Unresolved scientific +judgment calls remain comments, while a separately requested substantive revision +may be proposed from the supplied evidence. Never invent a result or justification. --- @@ -44,7 +58,7 @@ Use `skills/how-to-write-ideas-report/references/writing-workflow.md` for KB/con | 3 | Each paragraph has one well-defined job | 1 | `how-to-technical-writing` | | 4 | **DRY** — avoid repeated explanations/definitions | 1 | new to this skill | | 5 | Display math reserved for emphasis only | 1 | `write-paper` Notation Rulebook | -| 6 | Read the whole paper first; brief the story, judge it at the high level, then each section's mission | 0 | new — the gate before critique | +| 6 | Match context to scope; brief the story and section missions for a full review | 0 | scope and context selection | | 7 | Every figure referenced ≥1× and its striking features discussed | 1 | `write-paper` Figure Rulebook | | 8 | Verify factual claims & references; flag the uncertain | 2 | new — the standout capability | | 9 | Fit the target journal: limits, required parts, and its writing guidance | 2.5 | new — venue discussion reused from `write-paper` Phase 1.5 | @@ -63,25 +77,36 @@ Rank every finding so the user can triage: ## Phase 0 — Scope, load & understand (guideline #6) -1. **Resolve the manuscript.** Accept an explicit path; else auto-detect from `articles//` or the working directory. Detect format from the extension: **LaTeX (`.tex`) is primary**; Typst (`.typ`) and Markdown (`.md`) are supported. -2. **Ask what to check, before reading in depth.** Offer these numbered options; the user may pick any subset: - 1. **High-level story** — is the question worth asking, do the contributions match the results, and do the abstract, the main figure, and the supporting data carry the story (step 6 below). - 2. **Writing** — guidelines 1–7 (Phase 1), optionally narrowed to named guidelines or sections. - 3. **Facts, references, and links** — guideline 8 (Phase 2): every bibliography entry screened, cited claims sanity-checked, standalone factual claims verified, every URL and DOI link resolved. The slow pass. - 4. **Journal fit** — guideline 9 (Phase 2.5): decide or recommend the target journal, fetch its author guidelines, check limits and structural completeness, and review against the journal's own writing guidance. - - Default on a first review: all four. If a previous `articles//review-*.md` exists, say so and propose the repeat-pass default: option 2 only, restricted to text changed since that report, plus option 3 only if the bibliography changed, and option 4 only if the target journal changed or the previous report did not run it. A pass the user did not select is not run, and the report says it was skipped. -3. **Read the whole manuscript** end to end — and its bibliography. Resolve the bibliography in this order: the manuscript's own `\bibliography{…}` / `\addbibresource{…}` target (or embedded `thebibliography` / Typst `bibliography(…)`), then fall back to `$KB/references.bib`. Handle both; note which one you used. -4. **Load shared context.** Follow `skills/how-to-write-ideas-report/references/writing-workflow.md`: resolve `KB=$(python3 "$DOWNLOAD_REF_DIR/helpers/resolve_kb.py")`, read `$KB/INDEX.md`, `$KB/NOTES.md`, `$KB/references.bib`, and `docs/discussion/user-profile.md` if present. This is the literature backdrop for fact-checking. -5. **Write the story brief** (always, whatever was selected; it is the gate). Four short parts, in the paper's own terms: - - **Story** — one paragraph: what the paper does and what it finds. - - **Scientific question and its significance** — the question as the paper poses it, and why the field should care. State the gap the paper claims to fill. - - **Key contributions** — a numbered list, as the paper claims them. - - **Key results** — one line each, naming the figure, table, or equation that carries it. - - Then a one-line "mission" for each section. This gate prevents local nitpicks that fight the global narrative: if you misread the story, fix that before producing any finding. +1. **Resolve scope and mode.** Use the supplied manuscript, excerpt, requested + checks, and existing authorization. For an unspecified full review, cover + story, writing, facts/references, and journal fit when a target is known. + A local wording or caption request runs only the relevant writing checks. + Ask only when the target or substantive scope cannot be inferred. On a + repeat pass, inspect changed passages and affected dependencies; rerun + reference or journal checks only when relevant inputs or unresolved findings + changed. State any limits of the review. +2. **Read enough context.** For a full scientific review, read the whole manuscript + and its bibliography. For a local pass, read the target plus nearby definitions, + referenced equations/figures, and the context needed to preserve meaning. + Expand only if a concrete dependency requires it; do not require the entire + KB, user profile, or history for a local grammar check. +3. **Resolve references when needed.** Use the manuscript's own bibliography + (`\bibliography`, `\addbibresource`, embedded entries, or Typst bibliography) + before falling back to `$KB/references.bib`. For fact checks, follow the + relevant context/citation sections of + `skills/how-to-write-ideas-report/references/writing-workflow.md`. Load only + source entries relevant to the review, except in a requested full-bibliography + audit (Phase 2). +4. **Understand the story for a full review.** Write a brief covering the question, + significance, claimed contributions, key results tied to figures/equations, + and each section's mission. Include it with the completed report. Pause for + clarification only if competing interpretations would materially change the + critique. A local wording pass does not need a story-approval gate. +5. **Select passes.** The requested scope selects Phase 1 (writing), Phase 2 + (facts/references), and Phase 2.5 (journal fit). These correspond to options + 2, 3, and 4 below; option 1 means high-level scientific review. 6. **Comment on the high-level aspects** (option 1). Severity-ranked, same finding shape as Phase 1, guideline 6: - - **Significance of the problem** — Justify, from the manuscript and the loaded KB, why the problem is worth solving: who is blocked by it, what becomes possible once it is solved, and what the strongest prior attempt achieved. If the manuscript does not supply this, or the KB is too thin to judge whether the gap is real, say so and suggest a `survey` pass on the problem before the review continues; do not fill the gap from general knowledge. + - **Significance of the problem** — Justify, from the manuscript and the loaded KB, why the problem is worth solving: who is blocked by it, what becomes possible once it is solved, and what the strongest prior attempt achieved. If the manuscript does not supply this, or the KB is too thin to judge whether the gap is real, mark that assessment unresolved and suggest a focused literature check; continue other selected checks without inventing support from general knowledge. - **Significance of each contribution** — Take the numbered contributions one at a time. For each, ask: is it stated as a verifiable property (a bound, a measured improvement, a new capability with a demonstrated case) rather than an activity ("we study", "we explore")? Does a result in the paper verify it? Would a reader in the target audience pay for it: is it better than the strongest baseline on an axis that audience cares about, and is that axis named? A contribution that fails any of these is a finding; the fix names the property that would make it buyable. - **Story** — Does the claimed contribution match what the results actually show? Is the gap statement supported by the cited prior work, or asserted? - **Abstract** — Map its moves (system, method, finding, implication) onto the story brief. Flag any abstract claim no result backs, and any key result the abstract omits. @@ -89,7 +114,7 @@ Rank every finding so the user can triage: - **Supporting data** — For each key result, is the evidence strong enough for the claim as worded? Check the match between claim strength and evidence: a general claim needs more than one system, size, or seed; a "significant" improvement needs error bars or a statistical test that separates it from the baseline; a scaling claim needs enough decades to distinguish the fitted law from its neighbours; a "state of the art" claim needs the strongest current baseline, run under the same conditions. Flag claims with no data behind them, missing controls, baselines, or error bars, and claims worded stronger than the data. The fix either names the extra evidence needed or rewords the claim down to what the data shows. - **Highlighting the contributions** — Are the contributions where a skimming reader looks: named as such in the abstract, listed in the introduction's "in this paper" paragraph, and each tied to the figure or equation that proves it? Propose a better way to surface them when one exists: a main figure that puts the contribution and the strongest baseline on the same axes, a summary table of results versus prior work, a sharper title or abstract sentence that states the property rather than the activity, or reordering so the strongest result comes first. Keep to what the data already supports; do not invent a comparison. -Do not proceed to Phase 1 until the user confirms (or corrects) the story brief. The high-level comments are delivered with the brief; the user may reject any of them before they enter the report. +Continue through the selected passes and deliver one coherent report. Reuse a story the user already supplied or confirmed. --- @@ -105,7 +130,7 @@ Run only when option 2 was selected in Phase 0. Walk the manuscript and produce fix: a concrete suggested edit } ``` -Calibrate every `fix` against the model paper: Ho et al., PRL 122, 040603 (2019), at `skills/write-paper/sources/1807.01815_Ho2019_quantum-scars.md`, with a move-by-move walkthrough in `skills/write-paper/references.md` §C. A good rewrite reads like that letter: one concept per sentence, symbols defined at first use, each section opening with its job, main results named as such. When unsure whether a sentence deserves a finding, ask whether it could appear in the model paper unchanged. +When style calibration is needed, consult the relevant walkthrough in `skills/write-paper/references.md` §C; open only the corresponding excerpt of the model paper: Ho et al., PRL 122, 040603 (2019), at `skills/write-paper/sources/1807.01815_Ho2019_quantum-scars.md`, with a move-by-move walkthrough in `skills/write-paper/references.md` §C. A good rewrite reads like that letter: one concept per sentence, symbols defined at first use, each section opening with its job, main results named as such. When unsure whether a sentence deserves a finding, ask whether it could appear in the model paper unchanged. Checks: @@ -116,7 +141,7 @@ Checks: 5. **Display-math discipline.** Flag display equations that don't earn emphasis; suggest inlining or cutting. Reserve display math for key/flagship results, non-obvious steps, or figure-referenced equations. Never propose inlining or cutting an equation whose label is referenced elsewhere; for a letter, propose moving algebra to the supplement rather than deleting a reproducibility step. (`write-paper` Notation Rulebook.) 7. **Figure integration.** Flag **orphan** figures (never referenced in the main text) and figures whose striking features (peaks, kinks, jumps) aren't discussed. (`write-paper` Figure Rulebook.) -Also run a per-section **"did this section deliver its Phase-0 mission?"** check (guideline #6 carried into the body), and check that each key result from the story brief is named as a main result where it appears. +For full reviews, also run a per-section **"did this section deliver its Phase-0 mission?"** check (guideline #6 carried into the body), and check that each key result from the story brief is named as a main result where it appears. Every finding names the rule it serves. Not every paragraph needs a finding: a passage that already passes stays untouched, and a rewrite is never proposed for the sake of a diff. @@ -124,14 +149,15 @@ Every finding names the rule it serves. Not every paragraph needs a finding: a p ## Phase 2 — Fact & reference verification (guideline #8) -Run only when option 3 was selected in Phase 0. The standout capability. Follow the repo discipline: **never invent BibTeX from memory**. Bibliography metadata gets a complete automated screening pass; claim verification stays focused on what supports the main claims (see `skills/how-to-write-ideas-report/references/writing-workflow.md`). +Run only when option 3 was selected in Phase 0. The standout capability. Follow the repo discipline: **never invent BibTeX from memory**. Keep this pass within the selected scope: a full review screens all bibliography metadata, while a targeted fact or reference check verifies only the requested claims and their supporting entries/links; claim verification stays focused on what supports those claims (see `skills/how-to-write-ideas-report/references/writing-workflow.md`). -- **Screen every bibliography entry.** Run `python3 "$DOWNLOAD_REF_DIR/helpers/verify_bib.py" --bib "$BIB" --kb "$KB" --json` against the bibliography resolved in Phase 0. This checks uncited entries too and compares title, authors, year, venue/journal, volume, pages, and DOI using cached metadata plus Semantic Scholar's batch API. +- **Full review or bibliography audit: screen every bibliography entry.** Run `python3 "$DOWNLOAD_REF_DIR/helpers/verify_bib.py" --bib "$BIB" --kb "$KB" --json` against the bibliography resolved in Phase 0. This checks uncited entries too and compares title, authors, year, venue/journal, volume, pages, and DOI using cached metadata plus Semantic Scholar's batch API. +- **Targeted check.** Resolve the entries cited by the selected passage or named by the user and verify those records directly against authoritative metadata. Do not run `verify_bib.py` against the whole bibliography for this mode: its CLI has no key filter. Include additional entries only when they are dependencies of the requested claim. State the checked scope in the result. - **Confirm actionable records.** Use the helper's severity-ranked output as the starting point for the reference / fact-check table. Before reporting any `unverifiable` entry, or any `mismatch` with a high- or medium-severity finding, confirm it manually through **CrossRef → Semantic Scholar → MCP → web fetch**; Semantic Scholar screens, it is not the final authority. Keep low-severity missing-field findings as metadata-completion suggestions — they do not need the full lookup chain. Flag broken, missing, or confirmed-mismatched entries and offer repair via the `how-to-download-ref` skill (it owns `references.bib` appends and metadata fetching). -- **Citation resolution.** For each `\cite` key, confirm that an entry exists in the resolved bibliography. Uncited entries remain in the metadata scan; cited keys additionally participate in the claim-support check below. +- **Citation resolution.** For each `\cite` key in the selected scope, confirm that an entry exists in the resolved bibliography. In a full review, uncited entries remain in the metadata scan; cited keys additionally participate in the claim-support check below. - **Claim ↔ citation support.** For key claims attached to a citation, best-effort sanity-check that the cited work actually supports the claim. **Flag uncertain — do not assert.** -- **Standalone factual claims.** Identify checkable factual/numerical claims *not* tied to a citation; verify via web search. **Flag** the uncertain or unsupported — never silently "correct" a claim, and never fabricate a citation to prop one up. -- **Link check.** Every URL in the manuscript and bibliography (`\url`, `\href`, DOI links, code and data repositories) is fetched once; flag dead links, redirects to a different resource, and DOIs that do not resolve. A private or paywalled target that answers is ok. +- **Standalone factual claims.** Identify checkable factual/numerical claims in the selected scope *not* tied to a citation; verify via web search. **Flag** the uncertain or unsupported — never silently "correct" a claim, and never fabricate a citation to prop one up. +- **Link check.** Fetch relevant URLs and DOI links for a targeted check. In a full review, fetch every URL in the manuscript and bibliography (`\url`, `\href`, DOI links, code and data repositories) once; flag dead links, redirects to a different resource, and DOIs that do not resolve. A private or paywalled target that answers is ok. --- @@ -140,7 +166,7 @@ Run only when option 3 was selected in Phase 0. The standout capability. Follow Run only when option 4 was selected in Phase 0. Never quote a limit or rule from memory: every constraint in this pass comes from a page fetched in this session or from a `template/README.md` that records its source. 1. **Decide the target journal.** Use the venue the manuscript already declares: a document class or template (`revtex4-2`, `iopart`, `elsarticle`, an `sn-jnl` class), journal macros, a cover letter, or a `template/README.md` written by `write-paper` Phase 1.5. If none, follow `write-paper` Phase 1.5: propose 2–3 venues with tradeoffs (article type, audience, length pressure, figure limits, novelty bar) grounded in the story brief, and ask the user to pick one or say "no target yet". With no target, skip the rest of this pass and record that choice in the report. -2. **Fetch the author guidelines.** Prefer the official publisher page over mirrors, Overleaf copies, or lab handouts. Reuse `template/README.md` when it already records the URL and access date; otherwise record both in the report. If the page cannot be fetched, mark every constraint `unverifiable`, give the URL, and stop. +2. **Fetch the author guidelines.** Prefer the official publisher page over mirrors, Overleaf copies, or lab handouts. Reuse `template/README.md` when it already records the URL and access date; otherwise record both in the report. If the page cannot be fetched, mark every constraint `unverifiable`, give the URL, and stop that journal-constraint check while completing the other selected passes. 3. **Extract the checkable constraints into a table**: article type; word, page, or character limits for the body, abstract, and title; maximum figures, tables, and references; required sections and their order; required statements (data availability, code availability, author contributions, competing interests, funding, ethics or IRB, keywords, significance statement); formatting rules (citations in the abstract, footnotes, units, figure resolution and file types, reference style); and any writing guidance the journal itself gives (a first paragraph accessible to non-specialists, a summary-paragraph structure, a stated audience). 4. **Check each constraint against the manuscript.** Measure rather than estimate: word counts from the compiled text (`detex`, `pandoc --to plain`, or `typst query`), figure, table, and reference counts from the source, section presence from the headings. Status per row: ok / over / missing / unverifiable. Severity: high for a hard limit exceeded or a required statement missing, med for a formatting rule, low for cosmetic. 5. **Review against the journal's writing guidance.** Judge the abstract, the opening paragraph, and the framing of significance against what the journal says it wants for its audience. These are guideline-9 findings with the same shape as Phase 1; the fix cites the guideline sentence it serves. @@ -149,7 +175,10 @@ Run only when option 4 was selected in Phase 0. Never quote a limit or rule from ## Phase 3 — Deliver the review report -Write a timestamped report to `articles//review-YYYY-MM-DD.md` (the repo's dated-output convention). Structure: +For a full review, write `articles//review-YYYY-MM-DD.md` (or the requested +path). For a local excerpt or small wording pass, deliver concise findings or +the revised text inline unless a file was requested. Include only applicable +parts of this structure: 1. **Story brief, high-level comments, and per-section missions** (from Phase 0). 2. **Findings grouped by guideline, severity-ranked** (high → low). @@ -157,26 +186,46 @@ Write a timestamped report to `articles//review-YYYY-MM-DD.md` (the repo's 4. **Journal fit table** — target journal and guideline source (URL, access date), then constraint → required → measured → status. If Phase 2.5 was skipped or no target was chosen, one line saying so. 5. **Top fixes** — a prioritized list of the highest-leverage changes. -Then present a short summary to the user and ask two things: which findings to apply (all / by severity / individually), and whether to **show a marked diff first** or **apply directly**. Default to the marked diff; it costs one compile and lets the author judge each rewrite in context. +For a review-only request, deliver the report; offer application as an optional +next step. If changes were already requested, continue to Phase 4 using that +scope and the application mode from the Operating principle. For broad polish +without an established mode, deliver the marked proposal and numbered changes +for acceptance before merging; a generic revision request alone does not select +direct mode. Reuse explicit direct-edit instructions or already accepted +findings without asking again. A requested inline excerpt rewrite can be +delivered directly as revised text. --- ## Phase 4 — Apply approved edits -**Marked-diff mode** (the default). Never touch the original until the user has seen every proposed change in context. +**Marked-diff mode** (the default for broad revision/polish without an established +application mode, and whenever the user requests a preview). Prepare the +proposed changes before asking the user which to merge. Proposals outside the +authorized scientific scope remain separate suggestions, not applied edits. -1. **Edit a copy.** `cp main.tex main.proposed.tex` (same for `.typ` / `.md`). Apply every approved fix to the copy with a script that asserts each target passage matches exactly once. Comment-only fixes (style-guide guardrails) go in as `[reviewer]` comments in the copy too. +1. **Edit a copy.** `cp main.tex main.proposed.tex` (same for `.typ` / `.md`). Apply the proposed fixes to the copy; when using scripted replacements, assert that each target matches exactly once. Comment-only fixes (style-guide guardrails) go in as `[reviewer]` comments in the copy too. 2. **Mark the diff.** LaTeX: `latexdiff main.tex main.proposed.tex > main.diff.tex`, then compile `main.diff.tex` (deletions red struck-through, additions blue underlined). Typst and Markdown have no latexdiff; write `git diff --no-index --word-diff main.typ main.proposed.typ` into `articles//review-YYYY-MM-DD.diff` and, for Typst, also compile the proposed copy so the author can read the result. Check the page count did not change unexpectedly. + If shell/diff/render tools are unavailable, still create the proposed copy + with available file tools and provide numbered before/after changes. Report + the unavailable checks; do not ask whether to prepare the already requested + proposal. Acceptance concerns applying it to the original. 3. **Hand over a numbered legend.** Give the marked PDF (or diff file) path and one line per change: number, section and page, the finding it fixes, and the rule it serves. Pair up a removal and an addition that belong to one change. End with "reply with the numbers to merge, or all". 4. **Merge exactly the accepted numbers** into the original. If the user accepts "all except one wording", revert that wording in the copy first, then merge all. Delete `main.proposed.*` and `main.diff.*` afterwards. -**Direct mode** (only when the user chose it). Apply the approved findings straight to the manuscript. Do not edit anything the user didn't approve. +**Direct mode** (when the user asked to edit the original directly, approved +specific findings, or already chose this mode). Apply changes within that +authorization and show the diff/result. An explicit request such as "replace +'We studies' with 'We study' in this paragraph" authorizes that local edit; +a general "polish my paper" +uses the marked proposal by default. Do not broaden the requested revision or +ask again to apply changes already accepted. **Both modes.** 1. **Preserve structure.** Keep macros, environments, labels, and document structure in every format. Where a fix genuinely needs author judgment, insert a `% [reviewer] …` margin comment instead of rewriting silently (`// [reviewer]` in Typst, an HTML comment in Markdown). 2. **Language edits 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 guideline 1–5 fix; never replace a field term with a simpler word. Recheck every number, count, and qualifier a rewritten sentence mentions before moving on. -3. **Comment, do not apply, when a language fix touches content.** An edit that would change a quantifier or hedge ("arbitrary", "approximately", "at most"), add a justification the manuscript does not already contain, delete a paragraph as a digression, or remove a "not X but Y" contrast goes in as a `[reviewer]` comment even when the user approved the finding. The author writes those words. +3. **Comment, do not apply, when a language fix touches content.** An edit that would change a quantifier or hedge ("arbitrary", "approximately", "at most"), add a justification the manuscript does not already contain, delete a paragraph as a digression, or remove a "not X but Y" contrast goes in as a `[reviewer]` comment even when the user approved the finding. Do not treat approval of a language pass as approval to change scientific content; a substantive rewrite needs its own explicit scope and supporting evidence. 4. **Verify it still compiles** — `latexmk` (or `pdflatex`) for `.tex`, `typst compile` for `.typ`; for `.md`, confirm it still renders. Report pass/fail with the actual command output (per verification-before-completion: evidence before assertions). If it breaks, fix or revert the offending edit before claiming done. 5. **Append a changelog** to the top of the review report: what was applied, what was skipped, and the compile result. @@ -186,7 +235,7 @@ Then present a short summary to the user and ask two things: which findings to a **Reused (no duplication):** `skills/how-to-write-ideas-report/references/writing-workflow.md` (context, citations, output mechanics); `skills/how-to-technical-writing/SKILL.md` (sentence/paragraph rules, hunt table, application guardrails); the BibTeX lookup chain (CrossRef → Semantic Scholar → MCP → web fetch); `how-to-download-ref` for reference repair; `write-paper`'s notation/figure rule *definitions* (referenced). -**New here:** the read-whole-first review protocol (Phase 0), DRY/anti-repetition detection (#4), fact & reference verification (#8), journal fit (#9, venue discussion reused from `write-paper` Phase 1.5), and the comment-then-apply loop plus compile-check (Phases 3–4). +**New here:** scope selection and whole-paper context for full reviews (Phase 0), DRY/anti-repetition detection (#4), fact & reference verification (#8), journal fit (#9, venue discussion reused from `write-paper` Phase 1.5), and the comment-then-apply loop plus compile-check (Phases 3–4). --- @@ -194,13 +243,13 @@ Then present a short summary to the user and ask two things: which findings to a | Mistake | Instead | |---|---| -| Editing before the user approves | Comment-first. Phase 3 → user picks → Phase 4. | -| Merging a rewrite the author has not seen in context | Marked-diff mode by default: `latexdiff` on a copy, numbered legend, merge only the accepted numbers. | -| Nitpicking sentences before confirming the story | Phase 0 gate: confirm the story brief first. | -| Re-running reference verification on every pass | Ask what to check first, with the three numbered options; on a repeat pass default to writing only unless the bibliography changed. | +| Treating a review request as permission to edit | Deliver findings; use existing revision authorization only for its stated scope. | +| Treating broad polish as an implicit direct-edit preference | Default to a marked proposal; reuse explicit direct-edit instructions or accepted changes without another approval. | +| Running a full story gate for a local wording fix | Read the target and its necessary context; reserve the story brief for full reviews. | +| Re-running reference verification on every pass | Inspect changed inputs and unresolved findings; rerun only affected checks. | | Inventing a BibTeX entry to "fix" a citation | Never. Use the lookup chain / the `how-to-download-ref` skill, or flag as unverifiable. | | Silently "correcting" a factual claim | Flag uncertain claims; the author decides. | -| Claiming done without compiling | Run `latexmk` / `typst compile` and paste the result. | +| Claiming a build passed without running it | Compile changed document source; distinguish inline-text checks from a document build. | | Chasing completeness on fact-checks | Verify only what supports the main claims. | | Quoting a journal's word limit or required sections from memory | Fetch the official author guidelines this session, or mark the row unverifiable with the URL. | | Rewriting a passage that already passes | Leave it. A finding must name the rule it serves. | diff --git a/skills/review-paper/checklist.md b/skills/review-paper/checklist.md index 04bbba9..8d7a6c8 100644 --- a/skills/review-paper/checklist.md +++ b/skills/review-paper/checklist.md @@ -1,15 +1,15 @@ # Paper-reviewer process checklist -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. +The review-only items behind `review-paper/SKILL.md`: scope and context (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. --- -## 6 — Read the whole paper first (the gate) +## 6 — Scope and scientific context -- [ ] 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. 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. +- [ ] Scope and revision authorization were taken from the request; clarification was limited to missing information that changes the review. +- [ ] A full scientific review read the whole manuscript and bibliography; a local pass read the target and necessary dependencies. +- [ ] A full review includes the story, question, contributions, results tied to evidence, and section missions. Local wording checks do not require a story brief. +- [ ] The existing story was reused; only a material unresolved interpretation prompted a question. - [ ] 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. @@ -18,19 +18,19 @@ The review-only items behind `review-paper/SKILL.md`: the gate (6), fact and ref - 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.** +- [ ] The selected passes were completed before delivering the report, unless missing scientific input prevented an assessment. ## 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, and DOI were screened against cached and batched Semantic Scholar metadata. +- [ ] For a full review or bibliography audit, `verify_bib.py` screened every entry, including uncited entries. For a targeted check, only requested claims and their supporting entries were verified directly, and the limited scope was reported. +- [ ] Metadata fields in the checked scope were verified; full screening compares title, authors, year, venue or journal, volume, pages, and DOI 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. +- [ ] Every `\cite` key in the checked scope resolves to an entry in the bibliography that was actually used. - [ ] 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. +- [ ] Standalone checkable factual or numerical claims in scope are verified via web search. Uncertain ones are flagged. +- [ ] Relevant URLs and DOI links were checked for a targeted request; every manuscript/bibliography link was checked for a full review. 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) @@ -47,19 +47,19 @@ The review-only items behind `review-paper/SKILL.md`: the gate (6), fact and ref ## Language-pass hunt table (guidelines 1, 3, 4, 5) -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. +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** stay comments within a language pass; a separately requested substantive revision needs supporting evidence. ## Delivery & application -- [ ] 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. +- [ ] Full-review findings are saved to the requested path or `articles//review-YYYY-MM-DD.md`; a small excerpt review can be delivered inline. Findings are located and ranked by severity. +- [ ] A reference and fact-check table is included when that pass applies. - [ ] 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. The marked diff is the default. +- [ ] The chosen direct/diff mode was reused. Broad revision/polish without an established mode produced a marked proposal before changing the original. Explicit direct edits and accepted findings continued without another approval; an inline excerpt rewrite needed no application checkpoint. - [ ] 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. +- [ ] Applied edits stayed within the existing user authorization; a review-only request did not modify the original. - [ ] 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. -- [ ] The manuscript was re-compiled with `latexmk`, `pdflatex`, or `typst compile`, and the result was reported. +- [ ] Changed document source was compiled and the result reported. Inline-text checks did not claim a document build. - [ ] 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 7021ecd..1ee8986 100644 --- a/skills/write-paper/SKILL.md +++ b/skills/write-paper/SKILL.md @@ -5,77 +5,111 @@ description: User trigger. Use when drafting or revising a scientific manuscript ## 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` to its +real path before locating bundled resources. `skills//...` refers to the +installed skill found by public name, not the user's project; dependencies need +not be siblings. Load only resources needed for the current task. If a required +dependency is missing, report it before that dependent step. # Paper Writer -A working-rules guide for writing scientific papers, distilled from John Martinis's *Notes on Writing a Scientific Paper* and Jan von Delft's *Style Guide*. The source documents live in `references.md` and `sources/`; consult them when this SKILL.md leaves a question open. Beside them sits a model letter that executes these rules — Ho et al., PRL 122, 040603 (2019), see Source material. Imitate the model letter on any open style judgment call. +A working-rules guide for writing scientific papers, distilled from John Martinis's *Notes on Writing a Scientific Paper* and Jan von Delft's *Style Guide*. The source documents live in `references.md` and `sources/`; consult them when this SKILL.md leaves a question open. Beside them sits a model letter that executes these rules — Ho et al., PRL 122, 040603 (2019), see Source material. Use its relevant examples when a style judgment is unresolved, adapting to the manuscript and venue. **Scope note.** This skill is for *real manuscripts* — papers reporting completed (or near-complete) experimental, theoretical, or computational results. It is **not** for the upstream ideas/plan report produced by `brainstorm-ideas` report mode. If the user has not yet finished the work, push back: a paper requires results. -Use `skills/how-to-write-ideas-report/references/writing-workflow.md` for KB loading, citation handling, missing references, output formats, and Typst/diagram mechanics. The manuscript-specific rules below override shared defaults when venue templates or figure-first sequencing require it. +Use `skills/how-to-write-ideas-report/references/writing-workflow.md` for KB loading, citation handling, missing references, output formats, and Typst/diagram mechanics. Venue requirements take precedence over formatting defaults; the shared guide remains the source of sentence-level rules. --- -## The Iron Rules - -These seven override everything else. - -1. **Figures first, then prose.** Plot every figure you intend to publish *before* writing a single section. Figures are the backbone; the text serves them. If you cannot draw the story in 4–8 figures, you do not yet know the story. -2. **Polish what readers actually read.** 95% of readers read only the title, abstract, introduction, figures + captions, and conclusions. These five elements deserve disproportionate iteration. Write them last — *but iterate them most*. -3. **State main results explicitly.** Use at least one sentence per main result that names it as such: *"This figure / equation / observation is our (first / second / Nth) main result."* Do not assume the reader will identify which sentence is the punchline. -4. **One concept per sentence.** If you must break this rule, both concepts must be simple. Long compound sentences with three new ideas are how readers drop out. -5. **Never plot anything in arbitrary units.** If you reach for "a.u." on an axis, the axis is wrong; find the right normalization (dimensionless ratio, calibrated scale, or experimental control). "a.u." plots are a known integrity red flag. -6. **Target journal before story.** Before proposing story lines, discuss the target venue with the user and download its official author template. If the user deliberately has no target yet, record that choice. Venue constraints shape the narrative, figure count, length, and format. -7. **Iterate the story with the user.** Once the figures or figure plan are available and the target venue is known, propose 1–3 plausible story lines for the user to choose, reject, or combine. Do not draft prose until the user has selected the paper's narrative. - ---- - -## Workflow Phases - -A correct ordering of effort that defeats writer's block. Do not reorder — the sequence is the point. +## Choose the scope + +- **New manuscript:** default to the guided phases below, including unresolved + venue, story, and outline decisions with the user before full prose. The + supplied result, figure plan, or proof provides the evidence for those choices. +- **Continue an existing draft:** reuse its story, venue, outline, and figures. + Enter at the unfinished part and verify affected dependencies. +- **Broad revision or polish of an existing manuscript:** use `review-paper` + and carry forward the requested scope and application mode. With no mode + established, prepare a marked proposal before changing the original; reuse + direct-edit instructions or accepted findings without another approval. +- **Local revision:** change only the requested section, abstract, caption, or + passage, using its necessary context. Do not restart figure production, + venue selection, or story approval. For a critique rather than revision, use + `review-paper`. +- **Submission preparation:** apply the target venue's current requirements + and the relevant final checks. + +Carry forward choices and authorization from the conversation. A generic +"help me write a paper" uses the guided workflow; it does not by itself waive +the initial checkpoints. A supplied or previously approved venue, narrative, +or outline satisfies the corresponding checkpoint. If the user delegates the +remaining writing choices and asks for a complete draft without checkpoints, +state the choices you make and proceed, asking only for missing scientific +input that cannot be inferred. Never manufacture results, +references, or an unsupported claim. A writing request ends with the requested +text/source and appropriate checks; external feedback is optional. + +## Writing priorities + +Use figures, evidence, or a proof outline to organize the story. State each main +result clearly and connect it to its evidence. Give the title, abstract, +introduction, captions, and conclusions careful attention because readers use +them to judge the paper. Follow the shared style guide rather than imposing a +fixed sentence length or a template from a different scientific genre. + +## Workflow for a new manuscript + +Use the phases that the work still needs. For a theoretical result, a proof and +its key statements can serve the role of figures; a fixed figure count is not an +entry requirement. ### Phase 0 — Load context Before drafting, gather the materials that should inform the paper. Cheap to do once; expensive to skip. 1. **Shared writing context.** Follow `skills/how-to-write-ideas-report/references/writing-workflow.md`. Use `$KB/NOTES.md` as the spine for prior work, gap statement, motivation, and conclusions. -2. **Ideas / brainstorming log.** Look for `docs/discussion/*-brainstorm-ideas-log.md` from a prior `brainstorm-ideas` session. If present, read it for the original motivation, the cross-field connections it surfaced, the planned minimum viable experiment, and the success/hope/pivot signals. This is the *why* behind the paper and feeds the introduction's contribution claim. -3. **Personal publication context.** Read `docs/discussion/user-profile.md` and any `know-me-better` notes in `$KB/NOTES.md`. Use them to position the new paper in the user's own arc and to cite the user's earlier work correctly. +2. **Ideas / brainstorming log.** Look for `docs/discussion/*-brainstorm-ideas-log.md` from a prior `brainstorm-ideas` session. Read only logs relevant to this manuscript, starting with their summaries, for motivation, planned experiments, and success/hope/pivot signals. This is the *why* behind the paper and feeds the introduction's contribution claim. +3. **Personal publication context.** When positioning or self-citation requires it, read the relevant parts of `docs/discussion/user-profile.md` and `know-me-better` notes in `$KB/NOTES.md`. Use them to position the new paper in the user's own arc and to cite the user's earlier work correctly. 4. **Existing draft.** If a partial manuscript already exists under `articles/`, read it before proposing new prose; pick up where the user left off. -If none of these exist, name what's missing and ask the user to either point at the files or run the `survey` skill first. A paper without a literature foundation will read like one. +Use supplied source material even without a sci-brain KB. Research citation gaps needed by the draft; ask for missing results or assumptions that cannot be established from the available evidence. -### Phase 1 — Set up the figures (before writing any prose) +### Phase 1 — Establish the evidence and figure plan -- List the figures the paper needs. Aim for 4–6 in a letter, 6–10 in a regular article. +- List the figures or proof results needed to support the main claim; use the venue and argument to determine their number. - Order them so they *tell a story*: simple data first → progressively complex analysis → flagship comparison with theory. -- Draft each figure. Apply the **Figure Rulebook** (below). Do not move on until line weights, axes, colors, and dimensionless choices are right — going back later is more expensive than getting it right now. +- Draft needed figures using the **Figure Rulebook** below. Resolve issues affecting interpretation before writing claims around them; visual polish can proceed alongside the draft. - For each figure, write a one-sentence caption-summary: what the figure *shows* in plain words. These become the spine of the captions and the Results section. ### Phase 1.5 — Target journal and template checkpoint -Before the story checkpoint, stop and discuss the target journal or venue with the user. If the user has not chosen one, propose 2–3 plausible venues with tradeoffs: article type, audience, length pressure, figure limits, novelty bar, and format requirements. Ask the user to pick one target or to choose "no target yet" explicitly. In the latter case, record that no official template applies, and continue only after the user confirms this tradeoff. +Reuse a selected venue and installed template, including an existing decision +to draft without a target. For a new guided manuscript with no venue decision, +discuss plausible venues with audience, article type, length, novelty, and +format tradeoffs; let the user choose a target or "no target yet". For a local +revision, or when the user has delegated those choices and requested a draft, +do not reopen venue selection. If drafting without a target, record that status +and use the requested or existing format. Once a target is chosen: 1. Find the official author instructions and template from the journal or publisher website. Prefer official publisher pages over mirrors, GitHub copies, Overleaf community templates, or lab handouts. 2. Download the template package into the active manuscript directory, usually `articles/YYYY-MM-DD-/template/`. If no manuscript directory exists yet, create the article directory first. 3. Record the template source URL, access date, journal name, article type, and key constraints in a short `template/README.md` or manuscript note. -4. If the official template cannot be downloaded, explain why, save the author-instruction URL, and ask the user whether to continue with a generic draft format. -5. Do not propose story lines until the target venue and template status are clear. +4. If the official template cannot be downloaded, record the limitation and source URL. Continue a content draft in the existing format; ask only if the requested deliverable requires a template choice that cannot be inferred. +5. Apply known venue constraints to the story and figures; identify requirements that remain unverified. ### Phase 1.6 — Story checkpoint with the user -Before the telegram outline, stop and discuss the paper's narrative with the user. Base this only on the provided figures, caption-summaries, existing draft, loaded literature context, and target-journal constraints. +Reuse a narrative supplied or already selected by the user. In a new guided +manuscript, present the proposed story for the user's decision before full +prose, even if only one story is defensible. When the user has delegated the +narrative choice, state the evidence-based story you select and proceed. Base +the story on the provided results, figures, existing draft, literature, and +venue constraints; missing results cannot be replaced by a writing choice. + +When a narrative choice is still needed: 1. Propose **1–3 candidate story lines** for the user to pick from. If there is only one defensible story, present one strong option and say why alternatives would be forced. 2. For each story line, include: @@ -85,39 +119,39 @@ Before the telegram outline, stop and discuss the paper's narrative with the use - the audience or venue fit, - what the story deliberately de-emphasizes. 3. Ask the user to choose one, combine pieces, or reject them. If they push back, revise the story lines and ask again. -4. Only after the user selects or synthesizes a story, continue to the telegram outline. Treat the selected story as the contract for the draft. +4. Once the story is established, continue to the outline. Reopen that story only if new evidence changes the main claim. ### Phase 2 — Telegram outline - Write a telegram-style outline from the selected story line: section headings → bullet points → which figures and equations land where. - Mark which sentence in each section names a main result. -- Show the outline to a collaborator/advisor before you write prose. Cost of revision is lowest now. +- Reuse a supplied or approved outline. In a new guided manuscript, show the outline before drafting full prose; it may accompany the story proposal so the user can approve both together. If the user delegated outline decisions or authorized drafting from the established plan, use it as a working note and continue. Do not require a separate external advisor to approve it. -### Phase 3 — Draft the body in this order +### Phase 3 — Draft the body (a useful default order) 1. **Methods / Theory** — easiest to write; gets you over the activation barrier. 2. **Results** — walk the reader through the figures in order. For each figure: state what was varied (x-axis), what was measured (y-axis), what trend appears, where errors come from. Data is obvious to you, not the reader. -3. **Analysis** — explain how the data matches (or stretches) the theory. Plot data as points, theory as lines, on the same axes; arrange so theory lies on straight lines whenever possible. Discuss deviations larger than error bars *and* deviations much smaller than them (both are problems). +3. **Analysis** — compare data and theory under the stated uncertainty model. Investigate unexpected residuals rather than declaring large or small deviations an error by themselves; use the relevant Figure Rulebook guidance. 4. **Introduction (rough draft).** Do not perfect it yet. Hit four beats: (a) field-level question and why it matters, (b) prior work and what was missing, (c) what *this* paper does, (d) where the main results live (figure / equation pointers). The model letter executes all four in as many paragraphs, closing with "In this Letter, we develop…" — see `references.md` §C. Move on even if it feels weak. 5. **Conclusions.** Often a re-statement of the introduction in newly technical language — the reader now has the apparatus to absorb it. Add one paragraph on implications, applications, and follow-up directions. Acknowledgments and funding here. ### Phase 4 — Iterate the body -- Revise the body many times before touching abstract/intro polish. +- Revise until the argument, notation, and evidence support the requested draft. Repeat a pass only for a changed section, a failed check, or an unresolved finding. - Each pass: check the **One Concept Per Sentence** rule, check notation consistency, check that every striking feature in every figure is *explained in text*. - Last pass before Phase 5 is a **language pass**: walk the style guide's hunt table and change *how* sentences are written, never *what* they say. Do not add or remove a claim, figure, or derivation step in that pass; recheck every number and qualifier a rewritten sentence mentions; leave passages that already pass untouched. ### Phase 5 — Polish the high-leverage sections last - **Abstract:** one paragraph, 5–10 lines, ~one sentence per body section. The model paper does it in four moves — system, method, finding, implication — one move per sentence. Write it last, when you finally understand what the paper says. -- **Title:** descriptive, specific, scannable. Rewrite several times. +- **Title:** descriptive, specific, scannable. Refine it when it misstates or obscures the main claim. - **Introduction:** sharpen the opening hook, the gap statement, the contribution claim, and the forward-pointers to figures. - **Conclusions:** make the take-home messages crisp and quotable. -### Phase 6 — External feedback +### Optional external feedback -- Send to a friend / officemate who is *not* a co-author. -- Solicit comments from a known expert in the area. Most will oblige if you mention a deadline. Consider sending to known competitors as a goodwill gesture — they catch what reviewers will catch. +- When useful, suggest feedback from a reader outside the author list. External sharing is a separate user decision, not a completion gate for drafting. +- If the user requests expert feedback, help prepare the material and questions; contact others only when explicitly authorized. - Take every comment seriously. "Confusing to a friend" → "confusing to a reviewer." --- @@ -142,49 +176,16 @@ Most physics-style papers fit this. Short letters (PRL, Nature, Science) drop th ## Figure Rulebook -Figures are what readers remember; design them to survive the harshest viewing context. - -**Design for three uses simultaneously.** Each figure must work as: (a) inline figure in the paper, (b) slide in a beamer talk, (c) greyscale photocopy. Design for all three at draft time, not in a later retrofit. - -**Line weight.** Minimum thickness 2 for every curve (or at least the main-result curves). Thin lines vanish on a projector. - -**Color discipline.** -- Use saturated, robust colors: black, blue, red, dark orange, magenta, violet, dark brown. -- Avoid light yellow, light green, light grey — invisible when projected. -- Encode the distinction with a *line style* (solid / dashed / dash-dot) in addition to color, so the figure survives greyscale printing. -- In the caption, refer to features by line style, not color: "the dashed curve" not "the red curve". Add "(Color online)" if color matters. - -**Text size.** Axis labels, numbers, and legend text should not be much smaller than the surrounding paper text — at most 2/3 of body size. Tiny text wrecks the figure for talks. - -**Parameter labels.** Place key parameters (e.g., `T = 0`, `V = 0`, `Γ = 1`) directly inside the plot in small boxes. Saves caption length and makes the figure self-contained for talks. - -**Dimensionless axes.** Use dimensionless quantities (`G/G₀`, `T/Γ`, `V_g/Γ`, etc.) whenever possible — they generalize the result, clarify the relevant scale, and travel across systems. Choose the combination that maximizes message clarity; if you find a better one after plotting, replot. Exception: comparison with dimensional experimental data. - -**Data vs. theory.** Plot data as points (with error bars) and theory as lines, on the same axes. Arrange so theory lines are *straight* whenever possible — anyone can then check agreement at a glance. Use curved-theory plots only with a deliberate reason. - -**Error-bar reasoning.** Theory should pass through error bars on most points. Patterns to *discuss in text*: -- Many points deviating by more than an error bar → likely systematic error; address it. -- Error bars dwarfing the deviations → uncertainties likely overestimated; address this too. - -**Captions.** Concise but self-sufficient. Define every plotted quantity, summarize the trend, identify line styles. A reader who reads only the title, abstract, and figures+captions should get the paper. - -**Explain every striking feature.** Every peak, dip, kink, or jump that catches the eye must be discussed in the main text — ideally with a back-of-envelope reason. Unexplained features are either an honesty problem or a missed opportunity. If you genuinely don't understand a feature, say so in print and flag it for follow-up. - ---- +For figure creation or review, read the Figure Rulebook in +[figures-and-notation.md](references/figures-and-notation.md). Use intended display +size and scientifically meaningful axes; explain any normalization, including +arbitrary units when the measurement legitimately requires them. ## Notation Rulebook -Notation is the reader's interface to the math. Treat it with the same care as a public API. - -- **No symbol reuse in nearby sections.** Same letter must not mean two different things within a few pages. -- **If notation must change, signal it explicitly.** "Henceforth we use X to denote..." — never silent reuse. -- **Define every variable before using it.** Define them in logical order: earlier symbols define later ones, never the reverse. -- **If a better notation appears mid-project, switch and rewrite earlier sections.** The reader's cost of decoding bad notation is far higher than your cost of rewriting. -- **Compact vs. explicit formulas:** - - *Compact* when summarizing strategy, manipulating reader's high-level model, or when an expert could fill in the steps. - - *Explicit* when: highlighting a non-obvious step, presenting a trick that took real effort, showing a key intermediate result other work depends on, presenting a flagship result, or matching a plotted figure (cite the figure in the equation). - ---- +For mathematical writing, read the Notation Rulebook in +[figures-and-notation.md](references/figures-and-notation.md). Local prose edits +need only the definitions and notation used by the affected passage. ## Sentence-Level Rules @@ -192,54 +193,24 @@ Follow `skills/how-to-technical-writing/SKILL.md`: one concept per sentence, dir --- -## Pre-Submission Checklist - -Run this before clicking submit. Each item is cheap to check; missing any of them is expensive to fix in proof. - -**High-leverage text (read by 95%):** -- [ ] Title is descriptive, specific, scannable. -- [ ] Abstract reads as a one-paragraph summary, one sentence per body section. -- [ ] Introduction has all four beats (field interest, prior work, what's new, where main results live). -- [ ] Every figure has a caption that stands alone. -- [ ] Conclusions name the contribution and at least one implication. - -**Process gates:** -- [ ] Target journal or "no target yet" was discussed with the user before story selection. -- [ ] Official template was downloaded, or the failed/blocked/not-applicable template status was recorded. -- [ ] The user selected or synthesized a story line before prose drafting began. - -**Main-result labeling:** -- [ ] Each major result has a sentence explicitly tagging it as a main result. -- [ ] Each main result has a corresponding figure or equation. - -**Figures:** -- [ ] All curves are line-weight ≥ 2. -- [ ] All colors are saturated; no faint yellow/green/grey. -- [ ] Each figure is identifiable in greyscale (line styles distinguish, not just color). -- [ ] Axis numbers and legend text are readable from a slide. -- [ ] No axis labeled in arbitrary units. -- [ ] Every striking feature is explained in text. -- [ ] Data as points + theory as lines, plotted together, with straight theory lines where possible. - -**Notation and equations:** -- [ ] No symbol reuse for different meanings. -- [ ] Every symbol defined before use, in logical order. -- [ ] Explicit equations only for non-obvious steps, key intermediates, flagship results, or figure references. - -**Sentence-level:** -- [ ] No paragraph contains more than one new concept per sentence; sentences run about 20 words. -- [ ] Active voice dominates. -- [ ] Topic sentences open each paragraph. -- [ ] No "obviously" / "clearly": every asserted step names the earlier equation, figure, or section it rests on. -- [ ] No warm-up sentences, meta-talk about the document, or metaphors standing in for a precise statement. -- [ ] Technical terms kept; Latinate connectives ("hence", "conversely", "likewise") replaced by plain ones. -- [ ] Each paragraph stays on one object; each cross-reference says why the current step needs it. -- [ ] No run of inline computations; calculations sit in a display with one sentence naming what it shows. - -**External feedback:** -- [ ] At least one friend / officemate has read the full draft. -- [ ] At least one expert outside the author list has commented (when feasible). -- [ ] Comments have been addressed, not deflected. +## Finish the requested deliverable + +- Verify the requested sections say what the supplied results support and that + citations resolve. For new or changed figures, inspect the render at its + intended size using the Figure Rulebook. Check affected symbols and labels. +- For language changes, use `skills/how-to-technical-writing/checklist.md`; + preserve logical connectives and mathematical meaning. Sentence length is a + signal for overloaded clauses, not a word-count target. +- Compile changed source and resolve failures introduced by the change using + the shared writing workflow. For an inline excerpt, check the text and state + that no document build was run. Do not require a bibliography for a passage + that contains no citations. +- For submission preparation, also check current venue limits, statements, + template requirements, and unresolved author decisions. Do not submit or + distribute the manuscript without authorization. +- Deliver the draft/source or revised excerpt, relevant verification, and any + unresolved scientific questions. External reviews are not required to finish + a writing task. --- @@ -258,7 +229,7 @@ Run this before clicking submit. Each item is cheap to check; missing any of the ## Integrations - **Citations and missing references:** Follow `skills/how-to-write-ideas-report/references/writing-workflow.md`. -- **Manuscript format:** Use the target journal's official template when available. Default to Typst (`.typ`) only when no target venue or required template exists; use LaTeX (`.tex`) or Word when the journal requires it; use Markdown only for arXiv-style preprints where the journal accepts it. +- **Manuscript format:** Preserve the requested or existing format. Use the target journal's required format for submission preparation; a content draft can remain in Markdown, Typst, or LaTeX until a venue is chosen. - **Storing the draft:** `articles/YYYY-MM-DD-/` with `main.typ` (or `.tex`), a bibliography copied from `$KB/references.bib`, and `figures/`. --- @@ -268,7 +239,7 @@ Run this before clicking submit. Each item is cheap to check; missing any of the - `skills/how-to-technical-writing/SKILL.md` — the `how-to-technical-writing` skill: sentence- and paragraph-level rules shared with `review-paper`, with the hunt table and application guardrails. - `references.md` — distilled rule lists from Martinis (2012) and von Delft (style guide), plus a walkthrough of the model paper (§C). - `sources/NotesOnWritingPaper12.pdf` — the original Martinis notes. -- `sources/1807.01815_Ho2019_quantum-scars.md` — the model paper: Ho, Choi, Pichler & Lukin, *Periodic orbits, entanglement and quantum many-body scars in constrained models*, PRL 122, 040603 (2019), rendered from arXiv:1807.01815. This letter practices what the rules preach: one move per abstract sentence, the four introduction beats in order, run-in headers whose first sentence names the section's job, symbols defined at first use and then read back in plain words, figures that carry the story from page one. Skim it before drafting. `references.md` §C maps each move to its location in the paper. +- `sources/1807.01815_Ho2019_quantum-scars.md` — the model paper: Ho, Choi, Pichler & Lukin, *Periodic orbits, entanglement and quantum many-body scars in constrained models*, PRL 122, 040603 (2019), rendered from arXiv:1807.01815. This letter practices what the rules preach: one move per abstract sentence, the four introduction beats in order, run-in headers whose first sentence names the section's job, symbols defined at first use and then read back in plain words, figures that carry the story from page one. Read a relevant excerpt only when the distilled guidance leaves a style question open. `references.md` §C maps each move to its location in the paper. - von Delft's *Style Guide* online: The references preserve the *reasons* behind the rules; the model paper shows the rules executed. diff --git a/skills/write-paper/references/figures-and-notation.md b/skills/write-paper/references/figures-and-notation.md new file mode 100644 index 0000000..b898ced --- /dev/null +++ b/skills/write-paper/references/figures-and-notation.md @@ -0,0 +1,50 @@ +# Figures and notation + +Use only the rulebook relevant to the current artifact. Venue requirements and +scientific meaning determine how these defaults apply. + +## Figure Rulebook + +Figures are what readers remember; design them to survive the harshest viewing context. + +**Design for the intended display.** Use the target paper, slide, or print dimensions. Add grayscale-safe encodings when the venue or audience needs them. + +**Line weight.** Judge curves at final display size, using explicit units or plotting-library parameters. A single numeric width is not portable across renderers. + +**Color discipline.** Choose legible colors and redundant encodings at the intended size. The following are useful defaults, not a required palette. +- Use saturated, robust colors: black, blue, red, dark orange, magenta, violet, dark brown. +- Avoid light yellow, light green, light grey — invisible when projected. +- Encode the distinction with a *line style* (solid / dashed / dash-dot) in addition to color, so the figure survives greyscale printing. +- In the caption, refer to features by line style, not color: "the dashed curve" not "the red curve". Add "(Color online)" if color matters. + +**Text size.** Axis labels, numbers, and legend text should not be much smaller than the surrounding paper text — at most 2/3 of body size. Tiny text wrecks the figure for talks. + +**Parameter labels.** Place key parameters (e.g., `T = 0`, `V = 0`, `Γ = 1`) directly inside the plot in small boxes. Saves caption length and makes the figure self-contained for talks. + +**Dimensionless axes.** Use dimensionless quantities (`G/G₀`, `T/Γ`, `V_g/Γ`, etc.) whenever possible — they generalize the result, clarify the relevant scale, and travel across systems. Choose the combination that maximizes message clarity; if you find a better one after plotting, replot. Exception: comparison with dimensional experimental data. + +**Data vs. theory.** Plot data as points (with error bars) and theory as lines, on the same axes. A transformation that straightens a predicted relationship may help readers judge agreement. Keep transformations scientifically interpretable; straightening a theory curve is optional. + +**Error-bar reasoning.** Compare residuals against the stated uncertainty model, accounting for what each interval represents and any correlations. Patterns to investigate: +- Unexpected residual patterns relative to the uncertainty model → investigate model mismatch or systematic error. +- Residuals unexpectedly small relative to the uncertainty model → investigate uncertainty estimates, correlations, or overfitting; this alone does not establish an error. + +**Captions.** Concise but self-sufficient. Define every plotted quantity, summarize the trend, identify line styles. A reader who reads only the title, abstract, and figures+captions should get the paper. + +**Explain every striking feature.** Every peak, dip, kink, or jump that catches the eye must be discussed in the main text — ideally with a back-of-envelope reason. Unexplained features are either an honesty problem or a missed opportunity. If you genuinely don't understand a feature, say so in print and flag it for follow-up. + +--- + +## Notation Rulebook + +Notation is the reader's interface to the math. Treat it with the same care as a public API. + +- **No symbol reuse in nearby sections.** Same letter must not mean two different things within a few pages. +- **If notation must change, signal it explicitly.** "Henceforth we use X to denote..." — never silent reuse. +- **Define every variable before using it.** Define them in logical order: earlier symbols define later ones, never the reverse. +- **If a better notation appears mid-project, switch and rewrite earlier sections.** The reader's cost of decoding bad notation is far higher than your cost of rewriting. +- **Compact vs. explicit formulas:** + - *Compact* when summarizing strategy, manipulating reader's high-level model, or when an expert could fill in the steps. + - *Explicit* when: highlighting a non-obvious step, presenting a trick that took real effort, showing a key intermediate result other work depends on, presenting a flagship result, or matching a plotted figure (cite the figure in the equation). + +--- diff --git a/tests/test_write_paper_resources.py b/tests/test_write_paper_resources.py new file mode 100644 index 0000000..a3285c8 --- /dev/null +++ b/tests/test_write_paper_resources.py @@ -0,0 +1,29 @@ +"""Ensure moved paper-writing references work in an independent installation.""" + +import re +import shutil +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] + + +def test_write_paper_relative_references_work_without_sibling_skills(tmp_path): + installed = (tmp_path / "write-paper").resolve() + shutil.copytree(ROOT / "skills" / "write-paper", installed) + pending = [installed / "SKILL.md"] + visited = set() + + while pending: + source = pending.pop() + if source in visited: + continue + visited.add(source) + for link in re.findall(r"\]\(([^)]+)\)", source.read_text()): + if "://" in link or link.startswith("#"): + continue + target = (source.parent / link.split("#", 1)[0]).resolve() + assert target.is_relative_to(installed), (source, link) + assert target.is_file(), (source, link) + if target.suffix == ".md": + pending.append(target)