Academic Writing Loop

Academic Writing Loop: Academic English Proofreading (Single Pass / Loop)

Proofreads an English paper PDF as an academic editor familiar with scholarly writing. The standard is based on the checklist references/proofreading_checklist.md, adapted from Linda Olson's Guide to Academic and Scientific Publication (Proof-Reading-Service.com, 2014). The core principle of the guide is "follow submission guidelines, be accurate, be consistent." Many notations are acceptable either way, but inconsistency within a single paper is an error. Therefore, notation decisions are recorded in style_sheet.md and followed across all rounds.

Mode	What it does	Delivers to the user
Single pass	Proofreads the specified PDF once	Annotated PDF (highlights and comments with correction suggestions), proofreading report, style sheet
loop	Proofread → apply changes to the manuscript (LaTeX) and regenerate PDF → a different proofreader re-proofreads the new PDF, repeating until no more comments or up to the max round limit	Corrected PDF, annotated version of the original PDF, per-round reports and progress, change log, author queries

Below, <skill_dir> is the directory containing this SKILL.md, <ws> is the working folder, and AWL is shorthand for python <skill_dir>/scripts/awl.py. Use python3 if python is unavailable.

0. Launch: Determine Mode and PDF

Usage:

/academic-writing-loop 1回校正 paper.pdf
/academic-writing-loop loop paper.pdf
/academic-writing-loop loop 3 paper.pdf      ← Specify max rounds (default 5)

loop N means "proofread up to N times, apply changes (regenerate PDF) up to N−1 times." The process always ends with a proofread, so the final PDF shows exactly what remains.

Approximate time (test: 2-page, 640-word paper): Single pass ~15 minutes. Loop: first round is the longest; total ~45 minutes (3 proofreads, 2 revisions). Scales roughly linearly with page count.

1. Read the mode and PDF from the message (skill arguments). Delimiters can be spaces, "、", or ",".
   • Single pass: 1回校正 1回 一回 once single 1
   • Loop: loop ループ 繰り返し. The immediately following number is the max number of proofread rounds (default 5).
   • PDF: ends with .pdf. Resolve relative paths from the working directory; if not found, search by filename.
   • If the mode is missing, ask via a question tool (AskUserQuestion, or chat if unavailable): Single pass / loop (proofread → revise → re-proofread). If the PDF is missing, ask for that as well.
2. If the target journal name, submission guidelines URL, or US/UK preference is given in the message, use it. If not, don't ask (no journal = general academic English conventions; spelling = majority in the manuscript).
3. Check for PyMuPDF: python -c "import fitz". If missing, run python -m pip install pymupdf (required for annotated PDF and location info. If installation fails, continue without annotated PDF and inform the user).

1. Setup (Common to Both Modes)

Working folder: <PDF folder>/<PDF name>_awl/ (if writable, else under the working directory).

AWL init    <ws> --pdf <pdf> --mode once|loop [--max-rounds 5] [--journal "<Target journal>"]
AWL extract <ws>/rounds/r01/paper.pdf -o <ws>/rounds/r01/paper.txt
AWL scan    <ws>/rounds/r01/paper.txt -o <ws>/rounds/r01/scan.md

<ws>/
├── state.json         Mode, max rounds, stop reason (managed by awl.py)
├── style_sheet.md     Notation decisions (common across all rounds)
├── original/          Received PDF. Do not modify.
├── src/               Source for editing (loop only)
├── rounds/rNN/        paper.pdf paper.txt scan.md corrections.json report.md annotated.pdf
│                      revision_log.json (loop) src/ changes.diff (loop)
├── author_queries.md  Questions for the author (loop)
└── work/              Page images, etc.

• If extract warns "very little text per page", it's a scanned PDF. Inform the user that OCR (pdf skill) is required. If the body text is not in English, inform the user that this skill is not applicable and stop.
• If the target journal is known and web-accessible, read the official submission guidelines (Author guidelines / Instructions for authors) and record language/format rules (US/UK, word count, abstract structure, headings, citation style, figures/tables, abbreviations, keyword count) in style_sheet.md under "Target journal / guidelines" and each relevant line. Guidelines take precedence (Guide §3).
• In loop mode, briefly inform the user (2–3 lines): working folder, max rounds, and that you will proceed without further confirmation. For single pass mode, keep the summary for the final response.

2. One Round of Proofreading (Common to Both Modes)

The proofreading content follows references/proofreader_brief.md (procedure, how to write comments, JSON format) and references/proofreading_checklist.md (categories and severity).

Who performs the proofreading

• Single pass mode: You may do it yourself.
• Loop mode: Delegate each round to a new sub-agent (Agent tool). A proofreader without the context of the person who made the revisions can judge based solely on "what the PDF actually says," not "what was meant to be fixed." Rereading your own corrections in the same context increases oversights.
• Long papers (body text exceeding ~12 pages / 7,000 words): Split into page ranges (6–8 pages each, at section breaks) and assign to multiple sub-agents in parallel, then merge using AWL merge. After merging, you or the merge coordinator should check the whole paper for consistency (spelling, terminology, abbreviations, citations and references, figure/table numbers, headings) using the scan.md aggregation.
• If sub-agents are unavailable, do everything sequentially yourself. From round 2 onward in a loop, always read text extracted from the new PDF to proofread (don't judge from memory).

Instructions for the proofreading sub-agent (write all paths as absolute paths; the sub-agent's shell may reset its working directory between calls):

You are a professional academic English proofreader. Please read <skill_dir>/references/proofreader_brief.md and
<skill_dir>/references/proofreading_checklist.md to the end, and follow their procedures, standards, and output format.

- PDF to proofread: <ws>/rounds/rNN/paper.pdf (extracted text: <ws>/rounds/rNN/paper.txt)
- Mechanical check candidates: <ws>/rounds/rNN/scan.md
- Notation decisions: <ws>/style_sheet.md (fill in basic settings, terms, abbreviations for round 1)
- Previous round's comments: <ws>/rounds/r(NN-1)/corrections.json   ← only for round 2 and later
- Assigned pages: All pages   ← for division: "p.1–8" etc.
- Output: <ws>/rounds/rNN/corrections.json (for division: corrections.partK.json)
- Tools: python <skill_dir>/scripts/awl.py (validate / report / annotate),
         python <skill_dir>/scripts/pdf_tools.py render (view figure/table pages as images)
- Environment note: <e.g., Windows. Paths may contain Japanese characters/spaces, so enclose in quotes. Do not write outside <ws> and <skill_dir>.>

Do not change the author's meaning. Do not correct numbers, equations, quotations, or reference titles. If unsure, include as a query.
Finally, return "Count (errors/clarity/style/author queries), common error trends, validate result."

Always verify after proofreading (execute yourself even if delegated to a sub-agent):

AWL validate <ws>/rounds/rNN/corrections.json        # Make the proofreader fix until VALID
AWL report   <ws>/rounds/rNN/corrections.json        # → report.md
AWL annotate <ws>/rounds/rNN/paper.pdf <ws>/rounds/rNN/corrections.json -o <ws>/rounds/rNN/annotated.pdf

validate checks whether each original in the corrections actually exists in the PDF text. Any comment whose original text is not found indicates a transcription error or a comment on a nonexistent sentence; neither can be used for annotations or revision.

3. Single Pass Mode

1. Perform §2 for round r01.
2. AWL finalize <ws> → produces <ws>/<PDF name>_proofread.pdf (annotated) and <ws>/report.md.
3. Keep the response to the user brief:
   • Counts (errors / clarity / style / author queries) and overall assessment (2–3 sentences)
   • Top 3–5 most common error categories, each with one example (original → correction) and the rule name
   • List of author queries (brief)
   • File locations (annotated PDF: hover over highlights or open comments list to see corrections and reasons)
   • Do not paste the full report. Finally, add a brief note that loop mode can apply changes and regenerate the PDF.

4. Loop Mode

4.1 Prepare Source for Editing (May run in parallel with r01 proofreading)

init shows candidates for source files next to the PDF.

• LaTeX source available (.tex, folder, Overleaf or arXiv .zip / .tar.gz): Copy/extract to <ws>/src/ (main file contains \documentclass and \begin{document}). Build once and verify the source matches the PDF version:

  python <skill_dir>/scripts/build_pdf.py <ws>/src/<main>.tex --out <ws>/work/source_build.pdf
  AWL extract <ws>/work/source_build.pdf -o <ws>/work/source_build.txt
  AWL compare <ws>/rounds/r01/paper.txt <ws>/work/source_build.txt
  

  If similarity < 0.95, the versions likely differ. Ask the user which to use.
• No candidates found: Ask once if source (LaTeX / Overleaf zip) is available. Source makes revision accurate and fast.
• No source: Reconstruct LaTeX from the PDF following references/pdf_to_latex.md (delegate to a sub-agent in parallel with r01 proofreading; ~20–40 min for 10 pages). Emphasize that the layout is approximate and the English text (including errors) must be copied verbatim.
• Word (.docx) manuscript: This loop edits LaTeX. If preserving layout is important, applying corrections in Word based on the annotated PDF and report is more reliable. Ask the user which approach to take.
• Once ready, run python <skill_dir>/scripts/snapshot.py <ws>/src <ws>/rounds/r01.

4.2 Round r (r = 1, 2, …)

(a) Proofreading: §2. After finishing, output one line of progress to the user. E.g., r02 proofread complete: errors 9 / clarity 4 (previous 41 / 17), previous comments resolved 52/58

(b) Decision to continue: Run AWL status <ws> and follow the NEXT: line. The script decides when to stop (do not rely on your impression):

• Error + clarity comments reach 0 (convergence)
• Max rounds reached
• Error + clarity count did not decrease from the previous round (would only oscillate) NEXT: STOP → go to §4.3. The decision is made immediately after proofreading, so the final PDF is always proofread.

(c) Revision (apply round r comments and create the PDF for round r+1): Launch the revision sub-agent with the instructions below and wait for completion. Then verify yourself:

• rounds/r{r+1}/paper.pdf, paper.txt, scan.md exist. Build succeeded, zero undefined references.
• rounds/r{r}/revision_log.json exists, and AWL verify <ws> --round r succeeds (for items flagged by extraction, check page images; it's OK if marked verified_manually).
• If the build fails, restore broken files from rounds/r{r}/src/ and redo the revision. Never use an old PDF as a new version for proofreading.

→ Go to (a) for r+1.

Instructions for the revision sub-agent (absolute paths):

You are an editor working on behalf of the author, applying English proofreading comments to the manuscript. Please read
<skill_dir>/references/reviser_brief.md to the end and follow its rules (do not change meaning or data,
do not change text for queries, apply local → global).

- Source to edit: <ws>/src/ (main: <main>.tex)
- Current round's comments: <ws>/rounds/rNN/corrections.json (also refer to report.md)
- Notation decisions: <ws>/style_sheet.md (if a comment is rejected due to the author's intent or field conventions, add to "Items not changed")
- Author queries: <ws>/author_queries.md (append queries)
- New PDF: <ws>/rounds/rMM/paper.pdf (MM = NN+1). Follow §4 of reviser_brief.md for build, extract, scan, snapshot, revision_log.json, verify.
- Environment note: <same as proofreader>

Finally, return "Count of applied/rejected/author queries, build result, verify result, additions to style sheet."

4.3 Finalization

1. AWL finalize <ws> (if stopping for reasons other than the script's decision, e.g., user interruption, add --reason "<reason>"). Produces <PDF name>_corrected.pdf (final), <PDF name>_proofread_r01.pdf (annotated original PDF), <PDF name>_corrected_remaining.pdf (if any comments remain), changelog.md, progress.md. Author queries from the final round are not processed by the revision sub-agent; finalize appends them to author_queries.md.
2. (Optional) PDF with colored changes: Copy src/ to <ws>/work/diff_src/ to avoid contaminating the source.

   cp -r <ws>/src <ws>/work/diff_src
   latexdiff <ws>/rounds/r01/src/<main>.tex <ws>/src/<main>.tex > <ws>/work/diff_src/diff.tex
   

   If latexdiff exits non-zero or diff.tex is empty (common with MiKTeX due to missing Perl modules), skip and mention it in the response. On success, run build_pdf.py <ws>/work/diff_src/diff.tex --out <ws>/<PDF name>_diff.pdf.
3. Write <ws>/final_report.md:

   # English Proofreading Report: <Paper Title>
   - Mode / Rounds / Stop Reason / Target Journal & Spelling & Citation Style (from style sheet)
   ## Progress                           (table from progress.md)
   ## Trends in Original Manuscript       (r01 summary and per-category counts; common errors with examples and rules)
   ## Main Corrections Applied            (representative examples from changelog.md)
   ## Author Queries                      (author_queries.md, priority order)
   ## Remaining Comments                  (summary from final round report.md)
   ## File List
   

4. Keep the response to the user brief: number of rounds and progress (error + clarity counts), common error trends, top author queries, remaining comments, file locations. Do not paste the full report.

Resuming After Interruption

If <ws>/state.json exists, run AWL status <ws> to see the status and resume from the NEXT: step. init does not overwrite an existing working folder (use --force only to start over).

Principles and Rationale

• Do not change meaning or fabricate content: The object of proofreading is language, not research content. Do not change numbers, data, equations, quotations, reference titles, or the strength of claims. Anything the proofreader cannot decide alone should be returned as a query to the author. Since this is a real manuscript, guessing risks distorting the author's argument.
• Maintain consistency with the style sheet: Different proofreaders read each round; without recording decisions, we risk "change to UK → change back to US." Decisions are made in the order: submission guidelines → published papers in the journal → majority usage in the manuscript, and are not changed mid-process.
• Separate proofreading and revision: The proofreader comments based only on the PDF; the reviser verifies the correctness of each comment before applying it, and the next proofreader independently verifies the result. This catches errors missed or introduced during revision more effectively than self-review.
• Use automated checks: validate (is each comment about an actual sentence?), verify (did the revision make it to the PDF?), compare (does the reconstructed text match the original?)—these are numerical safeguards against language model hallucinations. Do not skip them.
• Let the script decide when to stop: Follow status's NEXT: line. A proofreader will always find something; continuing based on impression risks oscillating on stylistic preferences.
• Do not ask the user between rounds: By selecting loop mode, the user has approved execution up to the max rounds. Report only one line of progress; stop for consultation only on blockers (build failure, source/PDF version mismatch, unreadable PDF).
• Do not modify original files: Do not write to original/ or the user's original PDF/source. Edit copies in <ws>/src/.
• Treat the guide's outdated rules as style preferences: The guide (2014) advises against split infinitives and singular "they," but many modern style guides accept them. Do not mark these as errors unless the submission guidelines require otherwise.