Read the paper PDF and content / structure / sentence diagnose it across three layers, and create a review PDF with color highlights and margin cards attached over the body text. Each card consists of [Diagnosis] + [→ Alternative Direction], and the final page includes a revision roadmap organized in priority order.
Workflow
[입력: 원고 PDF]
↓
[1] 논문 전체 읽기 (모든 섹션, 부록 포함)
↓
[2] 3 층위 진단 (각 항목별로 본문에서 정확한 phrase 추출)
- 내용 (content): 통찰·기여·stake 누락
- 구조 (structure): 순서·배치 — architecture-first, 갑툭튀, 분산
- 문장 (sentence): verbosity·문체 — 수식 침투, 삽입구, 수동태
↓
[3] 우선순위 부여 (★ 최우선 / ▲ 중요 / 일반)
↓
[4] annotations.json 작성 후 build_review_pdf.py 실행
↓
[5] critic-loop: 페이지를 PNG으로 렌더링 → 자체 검토 → 재생성
Phase 1: Reading the Paper
Extract all PDF text and identify the section structure. Read the PDF directly with the Read tool, or extract text with an auxiliary script:
python3 -c "
import pypdf
r = pypdf.PdfReader('PAPER.pdf')
for i, p in enumerate(r.pages):
print(f'--- Page {i+1} ---')
print(p.extract_text())
" > paper_text.txt
Complete coverage by section: Read every section without omission, from the Abstract to the appendix. Because margin cards must precisely locate phrases in the body text, tracking which section and which paragraph is essential.
Phase 2: Three-Layer Diagnosis
Content — what is substantively missing
Representative patterns:
- Missing insight: Results and methods are present, but "what others missed" is not stated
- Abstract contribution: Only academic expressions like "measurable" and "reproducible," with no concrete follow-up use
- Absence of stake: The loss/threat of the problem is not stated, so the reader asks, "So what?"
- Weak bridge: Listing existing limitations → jumping to this study, with no corresponding mapping
- Lack of closure on the implications of results: Immediately after the results, there is no one line saying "what this means"
- Duplicated numbers: The body text copies the numerical values in the table verbatim
Structure — order and placement problems
Representative patterns:
- Architecture-first: Throwing out the result format first, such as 'orthogonal structure' or 'two layers,' with the motivation coming afterward
- Out of nowhere: A design decision whose motivation appears two sections later
- Scattering: The naming, role, and formula of the same tool are split across multiple sections
- Redundant definition: The same definition appears three times in the Abstract / §1 / §3
- Reversed order: The core insight is buried in the middle of the body text
- Awkward chapter boundaries: Essentially the same design decision, but split into §4 and §5
Sentence — verbosity and style
Representative patterns:
- Prose infiltration by formulas and symbols: Six or more variables embedded in one paragraph, breaking the flow
- Overuse of em-dashes: Two or more parenthetical asides in one sentence
- Passive voice: "is measured, is attributed, is confirmed" blurs the actor
- Nominalization: A sentence where only noun phrases pile up without a verb
- Triple parallelism: Tricolon appears more than twice in one paragraph
- Conditional introduction: The first sentence starts with "If ...", weakening the stake
- Abbreviation explosion: 12 or more abbreviations appear on one page
Phase 3: Prioritization
| Priority | Criteria |
|---|---|
| ★ Top priority (highest) | Directly connected to the core insight of the text itself. Fixing even one spot raises readability by one level |
| ▲ Important (high) | A key node in the problem's causal chain. Effective only when fixed together |
| (General normal) | Nice to polish |
★ Top priority is usually enough with 1-3 items. Too many dilutes the priority.
Phase 4: Writing annotations.json
JSON schema:
{
"schema": "paper-readability-review-v1",
"title": "Optional title for cover",
"subtitle": "Optional subtitle",
"one_line_diagnosis": "Optional one-line diagnosis for cover box",
"fontfile": "Optional path to CJK TTF (default: ~/.fonts/NanumGothic.ttf)",
"annotations": [
{
"page": 1,
"phrase": "정확히 PDF에서 매칭되는 본문 구절",
"category": "content | structure | sentence",
"priority": "highest | high | normal",
"diagnosis": "1-3문장 진단",
"alt": "1-2문장 대안 방향"
}
]
}
Important — phrase matching rules:
- Because of PDF line breaks, the phrase may be split. Use a short and unique phrase (usually 30-60 characters)
- PyMuPDF may not be able to match after an inline formula — choose text immediately before or after the formula
- If the same phrase appears multiple times, the first match is used
Build:
python3 build_review_pdf.py \
--input PAPER.pdf \
--annotations annotations.json \
--output PAPER_review.pdf
Phase 5: critic-loop
After generating the PDF, be sure to self-check:
python3 -c "
import fitz, os
os.makedirs('critic', exist_ok=True)
doc = fitz.open('PAPER_review.pdf')
for i in range(len(doc)):
doc[i].get_pixmap(dpi=140).save(f'critic/p{i:02d}.png')
"
Checklist while inspecting the generated PNG page by page:
- Do all cards fit within the page without being cut off?
- Is the card text readable even when small? (Font 8.0pt or larger recommended)
- Is the body highlight over the correct phrase?
- Is the core insight (★ top priority) shown prominently?
- Is the category distribution balanced?
- Are there 5 or fewer cards per page?
- Is the ★ top priority at the top of the priority roadmap page?
When a problem is found, modify annotations.json and rerun build. Usually 2-3 loops stabilize it.
Color and priority system (automatically applied by the build script)
| Category | Body highlight | Card label |
|---|---|---|
| content | Red | Content |
| structure | Blue | Structure |
| sentence | Yellow | Sentence |
| Priority | Badge |
|---|---|
| highest | Red ★ Top priority |
| high | Orange ▲ Important |
| normal | (No badge) |
Page layout (automatic)
- Add a 340pt margin to the right of the original page (612 → 952pt)
- Cards on each page are evenly divided between TOP=56 and BOTTOM=770 by the number of cards
- If it does not fit the slot, the font is automatically reduced (8.0 → 7.5 → 7.0 → 6.5pt)
- Connect body highlights ↔ cards with thin gray lines
- Automatically add a cover page (front) + priority roadmap (back)
Korean font
The default is ~/.fonts/NanumGothic.ttf. If not present, the build script downloads it automatically.
Troubleshooting
| Symptom | Cause | Solution |
|---|---|---|
[WARN] 'X' not found |
phrase does not match the PDF text exactly | Make the phrase shorter, immediately before/after the formula |
| Card clipped (overflow) | Too many cards or text too long | Recommended: 5 or fewer cards, diagnosis/alternative each within 100 characters |
| Korean characters broken (shown as ???) | Font file does not exist | Automatically download NanumGothic or specify fontfile |
| Only partially shown in the priority roadmap | Too many cards, exceeding one page | The build script automatically adds a page |
One line of inspiration
"Readability problems in a piece of writing usually flow from a single place. When the one sentence that is the starting point of every design decision is not clearly written in the body text — from this empty spot, the three symptoms of (1) unclear contribution, (2) logical jumps, and (3) verbosity are derived simultaneously. ★ The place to tackle with top priority is almost always that one sentence ."