paper-sentence-loop

A working loop for writing a manuscript with its author. The author reads each sentence in English and in their own language, reacts, and Claude answers each reaction with evidence before changing anything. The paper is improved part by part from versions the author already approved. It is never regenerated wholesale.

Evidence comes from the corpus-phrase-check skill (corpus_query.py). Scripts next to this file: import_draft.py (draft -> paragraph files), draft_lint.py (mechanical pre-check), build_hub.py (the review page).

The author reads in the hub and talks in chat. All text, tables and evidence go into one HTML page (draft/hub.html) that is rebuilt every round. The chat reply stays short: what changed, what to decide, then "허브 새로고침" (refresh the hub). Do not paste the sentence tables into chat when the hub is in use.

0. Start: what the author brings

Ask once for the target journal (it sets the register and the corpus to compare against). Then pick the entry point:

A. An existing draft (revise). Input: .docx / .md / .txt (a full manuscript or one section).

1. python import_draft.py <draft> --draft-dir draft splits it into paragraphs/<ID>_v0.json (A abstract, I introduction, P results/discussion, M methods). It never overwrites existing files. Fill the ko rendering for the paragraphs you show.
2. Seed terms.json from the draft and the figure labels: list every name used for the same object and ask which one to keep.
3. Run draft_lint.py on each paragraph once and put a short map in round R1 (paragraph · flags · longest sentence percentile). Do not fix anything yet.
4. Build the hub (it opens in the browser the first time). Ask which part to start with. Then go round by round (section 1), 1 to 2 paragraphs at a time.

B. A figure set, no text yet (draft new). Input: figure images or PDF, captions or panel notes, data tables if any, and an earlier manuscript or thesis chapter on the same work if one exists (use it as the base version).

1. Read every panel and write an outline first (outline.json: paragraph · the one claim it makes · the panels and values that support it · the citations it needs; the hub shows it as a table). One claim per paragraph. Get the author's approval on the outline before writing sentences.
2. Take numbers only from the figures, the data and the author. If a sentence needs a value that is not there, ask. Never fill it in.
3. Seed terms.json from the figure labels (axis quantities, sample names, stage names). Text and figures must use the same words.
4. Draft 1 to 2 paragraphs per round (section 1). Start where the author chooses. Results first is often easier than the Introduction.

C. Both. Start with A. Use the figure set as the basis column and to check that the text does not restate panels (rule 10).

0.1 Project files (create on first use, in the manuscript folder)

draft/
  hub.json                {"title", "journal", "lang": "ko"|"en", "native_label": "국문"}
  terms.json              term table, the single source of truth (template: templates/terms.example.json)
  paragraphs/P05_v3.json  one file per paragraph version (template: templates/paragraph.example.json)
  rounds.json             one entry per round (template: templates/rounds.example.json); the last one is "now"
  outline.json            entry B only: paragraph plan
  hub.html                built by build_hub.py, never edited by hand

Never overwrite an approved version. A change always makes _v<N+1>.json. Second language = Korean by default. Ask once if the author wants another language. Earlier manuscripts (a previous submission, a thesis chapter) are base versions. Find and load them before drafting anything new.

1. One round

Round number. Each author message (or a burst of messages sent while you work) is one round R<n>. Increase it even for a one-word fix. The author uses R numbers to track feedback.

Scope. Do 1 to 2 paragraphs per round. Never draft a whole figure's worth of text at once. Ask only the decisions that belong to that paragraph.

Every round ends the same way:

1. Write the paragraph version(s) (en, ko, basis, tool, changes).
2. Append the round to rounds.json: feedback (the author's words, short), done, parts, ask, and blocks for any measurement or proposal table.
3. python build_hub.py --draft-dir draft and reply in chat in 2 to 4 lines: what changed, what to decide, "허브 새로고침".

In the hub, each part is a sentence table (# · English · 국문 · basis · tool, widths 44/34/10/10 %), then a read-through of the paragraph, the changes, and earlier versions collapsed.

• Basis = the figure panel, number or citation that supports the sentence (short). Long quotes go in basis_full.
• Tool = what evidence picked the wording (corpus count, earlier version, source page) (short). Details go in tool_full.
• The Korean column is a faithful rendering for the author to judge meaning. Do not polish it into different content.
• Without the hub (a quick one-off question), use the same table in chat.

When the author gives "feel" feedback ("어색해", "길어", "갑작스러워", "범위가 좁아"): do not rewrite yet. Measure first:

1. Sentence length percentile (corpus_query.py length). At 35 or more words, always report the percentile and give split options.
2. Phrase counts for the current wording and 2 to 3 alternatives in both the general and domain corpora (corpus_query.py phrase).
3. The cited primary source: open the PDF and check the page when the sentence restates someone's result. Check that the conditions match (reaction, phase, method).
4. Earlier versions: how did the author's previous manuscript say the same thing?

Then put a proposal table in the round's blocks and stop:

{"t": "table", "title": "Proposals", "cols": ["#", "Now", "Proposal", "What changed", "Basis"], "rows": [["1", "...", "...", "...", "..."]]}

If the author says "아직 수정하지 말고" or "don't change yet", give the table only and write no new version. When the author picks items ("2, 4 적용"), apply only those and save P05_v4.json in the next round.

Revising an approved paragraph. Open the last approved version and change only the flagged phrase. Keep the wording that earlier rounds chose with corpus evidence. Do not re-insert experimental conditions that were moved to Methods to shorten a sentence. Do not rewrite the sentence from scratch.

2. Writing rules (self-check every sentence before showing it)

Run python draft_lint.py --file <paragraph> --terms draft/terms.json first. The lint gives prompts, and you make the decision.

1. Explicit subject + verb. Each sentence says what (a real actor: the catalyst, the applied power, we) does what (a measurable action). Avoid abstract subject + vague verb ("This approach enables ...", "temporal control shapes ...").
2. No pronoun references. Do not use it / its / this / that / them for a noun in an earlier sentence. Repeat the noun. Exception: only one candidate noun, immediately before. Never shorten a defined term ("low ratios" -> "low catalyst-to-substrate ratios").
3. One term per concept. Use only the forms in terms.json. Figures and text use the same words. If a new term is needed, propose a terms.json entry (use + first definition + basis) with corpus counts (see corpus-phrase-check section 2).
4. Few abbreviations. Define only those repeated in the main text. Spell out the rest.
5. Claim-evidence pairs. Every claim sentence carries or is followed by its evidence (panel, value, citation). Paragraph = claim -> evidence -> meaning. Use at most 2 compared value pairs per sentence, so numbers do not bury the claim.
6. No colon joining claim and evidence. Write two sentences.
7. Linking. Each sentence connects to the previous one (connective, repeated noun, cause -> result). No bare noun-phrase sentence that jumps in without a link inside a paragraph. If a sentence feels abrupt, give the reason before the number.
8. Intensifiers. Before replacing "significantly" or "markedly", ask what the word was doing (signal of a reversed expectation, verdict summary, size of a comparison). Replace it only if the sentence lacks the value or reference it implies.
9. Expert reader. The judge is an expert in the target journal reading once. Do not argue for plain-language paraphrase on "readability" grounds. Look first for the precise technical term that compresses the idea ("high heat capacity and low thermal diffusivity" rather than "holds heat").
10. Figures are read with the text. If a figure shows it, the text says what it means. Do not say where or how it is drawn. (Fig. 4a) at the end of a sentence is enough. Do not write "the two curves drawn in Fig. 4a" or "see Fig. 4a".
11. Confident within the method's limits. State a limit once, as a fact that sets the scope. Then state conclusions inside that scope without stacked hedges. Do not pre-defend against questions nobody asked ("this is only an observation, not a factor"). Keep negative results as data. Rewrite negative author caveats as what was done.
12. Deletion gate. Before deleting a clause that looks like a caveat, ask what it tells the reader to take from the previous sentence. If it carries that job, convert it to a positive statement instead of deleting it.
13. Conflicting literature. Do not escape a conflict by narrowing to a condition ("because ours is liquid-phase"). State what was measured, and put condition differences in Methods/SI as facts. Claim "first" only for an explicit keyword intersection, and only after a literature search.
14. Abstract. Open on the problem and the measured result. No numbers or citations from other papers.
15. Hedges from sources. Do not copy a source's "often" or "may". Check if the scope can be narrowed so the hedge is no longer needed.
16. Numbers. Check every numeric claim against the source page or data file yourself. Do not trust a paraphrase.

3. Reporting a revision

• Conclusion first. Then quote what was removed or changed and why (redundant claim, repeated wording, excess detail), using the original words.
• Do not report style metrics as the goal. Percentiles diagnose. One line at the end at most.
• Judge sentence by sentence. Some sentences should change and some should stay. Do not push the paragraph toward corpus medians. In a paragraph made of short sentences, the right fix can be adding a sentence that answers an expectation set earlier.

4. The hub page

python build_hub.py --draft-dir draft writes draft/hub.html, top to bottom:

1. Review now: the current round, its parts and the questions to decide.
2. The part cards of the current round, then the round's blocks (measurements, proposal tables).
3. Earlier rounds, collapsed.
4. The whole manuscript: a table of every paragraph (latest version, status, words) and an expandable read-through.
5. Term table, outline (entry B), round log (newest first).

Rules:

• Keep it to one page that grows. Never make a new HTML file per round.
• It opens in the browser only when first created. Afterwards, rebuild and tell the author to refresh. --open forces it, --no-open suppresses it.
• ^{..} and _{..} in sentences render as superscript and subscript (CO_{2}, cm^{-1}).
• Images in a round block use paths relative to draft/.