subsection-polisher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Subsection Polisher (local, pre-merge)

小节润色工具（本地，合并前）

Purpose: upgrade one

sections/S<sub_id>.md

(H3 body-only) so it reads like survey prose before you merge into

output/DRAFT.md

This is intentionally local: fix one unit at a time, rerun gates, and converge without rewriting the whole paper.

用途：在将

sections/S<sub_id>.md

（仅H3正文内容）合并到

output/DRAFT.md

之前，将其升级为符合调研论文风格的文稿。

本工具专为本地操作设计：一次修复一个单元，重新运行检查门控，逐步完善而无需重写整篇论文。

Role cards (use explicitly)

角色卡片（需明确使用）

Local Section Editor

本地章节编辑

Mission: improve one H3’s argument density and paper voice without changing citation keys.

Do:

Rewrite the opener as tension -> why it matters -> thesis (end paragraph 1 with thesis).
Add explicit contrasts and one evaluation anchor when missing.
Add a subsection-specific limitation that changes interpretation.

Avoid:

Adding/removing citation keys or moving citations across subsections.
Replacing content with generic boilerplate.

任务：在不修改引用键的前提下，提升单个H3小节的论证密度和论文语气。

需执行：

将开篇重写为「矛盾点→重要性→论点」结构（第一段结尾需点明论点）。
补充缺失的明确对比内容和一个评估锚点。
添加一个小节专属的局限性内容，且该内容会影响解读方向。

需避免：

添加/删除引用键，或跨小节移动引用内容。
用通用模板内容替换原有内容。

Evidence Steward (stop padding)

证据管理员（防止冗余填充）

Mission: prevent polishing from turning into invention when evidence is thin.

Do:

If you cannot write a contrast or evaluation anchor without guessing, stop and route upstream.

Avoid:

Strengthening claims beyond what the existing citations can support.

任务：当证据不足时，避免润色过程演变为编造内容。

需执行：

如果无法在不猜测的前提下写出对比或评估锚点，立即停止并向上游环节反馈。

需避免：

提出超出现有引用内容支撑范围的主张。

Role prompt: Local Section Editor (one H3 at a time)

角色提示词：本地章节编辑（一次处理一个H3小节）

text

You are editing one survey subsection to make it read like paper prose.

Your goal is to remove generator voice and strengthen argument moves without changing citation keys:
- opener: tension + why-it-matters + thesis (no narration)
- add explicit contrasts and an evaluation anchor if missing
- make at least one cross-paper synthesis paragraph (>=2 citations)
- add a subsection-specific limitation (not boilerplate)

Constraints:
- do not add/remove citation keys
- do not invent facts
- keep scope local to this H3

text

You are editing one survey subsection to make it read like paper prose.

Your goal is to remove generator voice and strengthen argument moves without changing citation keys:
- opener: tension + why-it-matters + thesis (no narration)
- add explicit contrasts and an evaluation anchor if missing
- make at least one cross-paper synthesis paragraph (>=2 citations)
- add a subsection-specific limitation (not boilerplate)

Constraints:
- do not add/remove citation keys
- do not invent facts
- keep scope local to this H3

Inputs

输入项

Target file:
```
sections/S<sub_id>.md
```
(H3 body-only)
Preferred context:
```
outline/writer_context_packs.jsonl
```

Fallback context:

outline/subsection_briefs.jsonl

outline/evidence_drafts.jsonl

```
citations/ref.bib
```

目标文件：
```
sections/S<sub_id>.md
```
（仅H3正文）
优先参考上下文：
```
outline/writer_context_packs.jsonl
```

备选参考上下文：

outline/subsection_briefs.jsonl

outline/evidence_drafts.jsonl

引用文件：
```
citations/ref.bib
```

Output

输出项

Updated
```
sections/S<sub_id>.md
```
(same path; citation keys unchanged)

更新后的
```
sections/S<sub_id>.md
```
（路径不变；引用键保持原样）

Non-negotiables (contract)

不可协商规则（约定）

Citation keys are immutable: do not add/remove any
```
[@BibKey]
```
markers.
Scope is immutable: keep all citations within this H3’s allowed scope (
```
outline/evidence_bindings.jsonl
```
/ writer pack
```
allowed_bibkeys_*
```
).
No invented facts: if you cannot write a concrete contrast or evaluation anchor without guessing, stop and fix upstream evidence.
Body-only: no headings;
```
section-merger
```
adds headings.

引用键不可修改：不得添加/删除任何
```
[@BibKey]
```
标记。
范围不可修改：所有引用内容需限定在当前H3小节的允许范围内（参考
```
outline/evidence_bindings.jsonl
```
/ 作者包中的
```
allowed_bibkeys_*
```
）。
不得编造事实：如果无法在不猜测的前提下写出具体的对比或评估锚点，立即停止并修复上游证据缺口。
仅保留正文：不得添加标题；标题将由
```
section-merger
```
工具统一添加。

Target quality (what “polished” means)

目标质量标准（“润色完成”的定义）

A polished H3 reads like an argument, not a topic list:

Paragraph 1 ends with a thesis (conclusion-first takeaway) and does not use narration templates.
At least two explicit contrasts (A vs B) using contrast words.
At least one evaluation anchor paragraph (task/benchmark + metric + constraint/budget/tool access when relevant).
At least one cross-paper synthesis paragraph with >=2 citations in the same paragraph.
At least one limitation/caveat tied to protocol mismatch / missing details / unclear threat model (not boilerplate).

润色后的H3小节需具备论证逻辑，而非简单罗列内容：

第一段结尾需点明核心论点，且无叙述式开篇。
至少包含2处明确对比（A vs B），使用对比类词汇。
至少包含1个评估锚点段落（任务/指标/约束条件）。
至少包含1个跨论文综合分析段落（引用数量≥2）。
至少包含1个小节专属的局限性/说明（非通用模板内容）。

Paper voice constraints (high signal anti-patterns)

论文语气约束（高辨识度反模式）

Delete / rewrite these (they read like a generator):

Outline narration:

This subsection ...

In this subsection, we ...

Slide navigation:

Next, we move ...

We now turn to ...

In the next section ...

Meta guidance:
```
survey synthesis/comparisons should ...
```
.
Evidence-policy disclaimer spam: repeated
```
abstract-only/title-only/provisional
```
boilerplate inside H3.
Count-based slot openers: repeated "Two limitations..." / "Three takeaways..." used as paragraph starters.

Prefer these (paper voice):

Content-first openers:

A central tension is ...

In practice, ...

One recurring pattern is ...

Argument bridges (not navigation):

This contrast matters because ...

These assumptions shape ...

Embedded citations as evidence (no trailing dump tags).

需删除/重写以下内容（此类内容带有生成器语气）：

叙述式开篇：

This subsection ...

、

In this subsection, we ...

。

幻灯片式导航语：

Next, we move ...

、

We now turn to ...

、

In the next section ...

。

元指导语：
```
survey synthesis/comparisons should ...
```
。
重复的证据政策免责声明：H3小节内反复出现的
```
abstract-only/title-only/provisional
```
等模板化内容。
基于计数的开篇：反复使用“Two limitations...” / “Three takeaways...”等作为段落开头。

推荐使用以下风格（符合论文语气）：

内容优先的开篇：

A central tension is ...

、

In practice, ...

、

One recurring pattern is ...

。

论证衔接语（而非导航语）：

This contrast matters because ...

、

These assumptions shape ...

。

引用内容作为证据嵌入正文（而非在段落末尾批量罗列）。

Workflow (one subsection)

工作流程（单个小节）

Load the subsection contract

Read this subsection’s pack in
```
outline/writer_context_packs.jsonl
```
.
If the pack is missing/thin, fall back to
```
outline/subsection_briefs.jsonl
```
(thesis/tension/paragraph_plan) +
```
outline/evidence_drafts.jsonl
```
(comparisons/eval/limitations).
Extract (write down, not in the prose):
- ```
tension_statement
```
  +
```
thesis
```
- 2–3
```
comparison_cards
```
  you will use for A-vs-B contrasts
- 1
```
evaluation_anchor_minimal
```
  (task/metric/constraint)
- 1 limitation hook from the evidence pack

Preflight (kept out of the final prose)

Draft 4 one-line sentences:
- Tension
- Contrast (A vs B; >=2 citations)
- Evaluation anchor (task/metric/constraint)
- Limitation If you cannot write these without guessing, stop and push the gap upstream (
```
paper-notes
```
  /
```
evidence-draft
```
  ).

Opener rewrite (paragraph 1)

Remove narration openers.
Write: 1–2 sentences tension/decision/lens + 1 sentence why it matters + end with the thesis.

Bad:

This subsection surveys tool interfaces for agents.

Better:

A central tension in tool interfaces is balancing expressive action spaces with verifiable execution; interface contracts largely determine which evaluation claims are meaningful.

Paragraph pass (argument moves > listing)

Rewrite paragraph-by-paragraph using the
```
grad-paragraph
```
micro-structure:
Best-of-2 rewrite (recommended): when a paragraph feels slot-like, draft 2 candidate rewrites and keep the one with clearer argument move + less template cadence (citations unchanged).
- tension → contrast → evaluation anchor → limitation
Ensure you include:
- =2 explicit contrasts (not “A then B” summaries)
- =1 evaluation anchor paragraph
- =1 cross-paper synthesis paragraph (>=2 citations)
- =1 limitation paragraph/clause that is subsection-specific

Citation embedding pass (no dumps)

Rewrite paragraphs where citations appear only at the end as
```
[@a; @b; @c]
```
.
Ensure every citation key you keep is defined in
```
citations/ref.bib
```
.

Bad (dump):

Many systems adopt tool schemas. [@a; @b; @c]

Better (cite-as-evidence):

Systems such as X [@a] and Y [@b] formalize tool schemas to reduce action ambiguity, whereas Z [@c] keeps the interface looser and shifts the burden to validation.

Rhythm + de-template pass

Vary paragraph openings; avoid repeating the same synthesis stem across many paragraphs (especially
```
Taken together
```
).
Delete empty glue sentences that don’t add a claim, contrast, protocol detail, or limitation.

Recheck (do not skip)

Run
```
section-logic-polisher
```
and address FAILs (thesis + connector density) without changing citation keys.
Rerun
```
writer-selfloop
```
(or the strict quality gate) and fix only what the report flags.

加载小节约定

读取
```
outline/writer_context_packs.jsonl
```
中对应小节的内容包。
如果内容包缺失/内容单薄， fallback到
```
outline/subsection_briefs.jsonl
```
（论点/矛盾点/段落规划） +
```
outline/evidence_drafts.jsonl
```
（对比/评估/局限性内容）。
提取（仅用于内部参考，不写入最终文稿）：
- ```
tension_statement
```
  +
```
thesis
```
  （矛盾点陈述 + 论点）
- 2–3个用于A-vs-B对比的
```
comparison_cards
```
  （对比卡片）
- 1个
```
evaluation_anchor_minimal
```
  （最简评估锚点：任务/指标/约束条件）
- 1个来自证据包的局限性切入点

预检查（不写入最终文稿）

草拟4个单句：
- 矛盾点
- 对比内容（A vs B；引用≥2）
- 评估锚点（任务/指标/约束条件）
- 局限性如果无法在不猜测的前提下写出这些句子，立即停止并向上游环节反馈（
```
paper-notes
```
  /
```
evidence-draft
```
  ）。

重写开篇（第一段）

删除叙述式开篇。
写作结构：1–2句矛盾点/决策/视角 + 1句重要性说明 + 结尾点明论点。

反面示例：

This subsection surveys tool interfaces for agents.

正面示例：

A central tension in tool interfaces is balancing expressive action spaces with verifiable execution; interface contracts largely determine which evaluation claims are meaningful.

段落逐句优化（论证优先于罗列）

按照
```
grad-paragraph
```
微结构逐段重写：
推荐采用“二选一重写法”：当段落显得模板化时，草拟2个重写版本，选择论证逻辑更清晰、模板感更弱的版本（引用键保持不变）。
- 结构顺序：矛盾点 → 对比 → 评估锚点 → 局限性
确保包含：
- ≥2处明确对比（而非“A接着B”的简单总结）
- ≥1个评估锚点段落
- ≥1个跨论文综合分析段落（引用≥2）
- ≥1个小节专属的局限性段落/分句

引用嵌入优化（避免批量罗列）

重写那些仅在段落末尾以
```
[@a; @b; @c]
```
形式批量罗列引用的段落。
确保保留的所有引用键均在
```
citations/ref.bib
```
中有定义。

反面示例（批量罗列）：

Many systems adopt tool schemas. [@a; @b; @c]

正面示例（作为证据嵌入）：

Systems such as X [@a] and Y [@b] formalize tool schemas to reduce action ambiguity, whereas Z [@c] keeps the interface looser and shifts the burden to validation.

节奏调整与去模板化

变换段落开头方式；避免在多个段落中重复使用相同的综合分析开头（尤其是
```
Taken together
```
）。
删除无意义的衔接句，此类句子未添加任何主张、对比、协议细节或局限性内容。

二次检查（不可跳过）

运行
```
section-logic-polisher
```
工具，处理所有标记为FAIL的问题（论点 + 衔接密度），且不修改引用键。
重新运行
```
writer-selfloop
```
（或严格质量检查门控），仅修复报告中标记的问题。

Rewrite recipes (common failure -> fix)

重写方案（常见问题→修复方法）

Use these as rewrite intentions, not copy-paste templates.

Narration opener -> content claim

This subsection surveys ...

A central tension is ...; this matters because ...

(end paragraph 1 with the thesis).

Slide navigation -> argument bridge

Next, we move from planning to memory.

Planning specifies how decisions are made; memory determines what information those decisions can reliably condition on under a fixed protocol.

Disclaimer spam -> one policy paragraph + local caveat only

Delete repeated
```
abstract-only evidence
```
boilerplate.
Keep evidence policy once in Intro/Related Work; in H3, only add a local caveat when it changes the interpretation of a specific comparison.

Meta “survey should” -> literature-facing observation

Therefore, survey comparisons should control for tool access.

Across reported protocols, tool access and budget assumptions vary widely, making head-to-head comparison fragile unless those constraints are normalized.

Too-vague quantitative claim -> add minimal context (or weaken)

If a paragraph keeps a number, add: task type / metric definition / constraint (budget/cost/tool access) in the same paragraph and keep the citation embedded.
If the context is unknown from the evidence pack, rewrite the claim as qualitative and mark the missing field as a verification target (without boilerplate).

以下方案为重写意图，而非可直接复制粘贴的模板。

叙述式开篇 → 内容主张式开篇

This subsection surveys ...

→

A central tension is ...; this matters because ...

（第一段结尾点明论点）。

幻灯片式导航语 → 论证衔接语

Next, we move from planning to memory.

→

Planning specifies how decisions are made; memory determines what information those decisions can reliably condition on under a fixed protocol.

重复的免责声明 → 单次政策说明 + 仅添加局部说明

删除重复的
```
abstract-only evidence
```
等模板化内容。
证据政策仅在引言/相关工作部分说明一次；在H3小节中，仅当局部说明会改变特定对比的解读方式时才添加。

元指导语“survey should” → 面向文献的观察

Therefore, survey comparisons should control for tool access.

→

Across reported protocols, tool access and budget assumptions vary widely, making head-to-head comparison fragile unless those constraints are normalized.

过于模糊的量化主张 → 添加最简上下文（或弱化表述）

如果段落保留了数字，需在同一段落中添加：任务类型 / 指标定义 / 约束条件（预算/成本/工具权限），并将引用嵌入其中。
如果从证据包中无法获取相关上下文，将主张重写为定性描述，并将缺失字段标记为验证目标（无需模板化内容）。

Stop conditions (when polishing is the wrong move)

停止条件（润色并非最优解的场景）

Stop and go upstream if:

you cannot write a contrast without guessing (evidence pack is title/abstract-only)
the subsection lacks evaluation anchors (no benchmarks/metrics/protocol details in notes)
you keep needing out-of-scope citations to make the argument work

当出现以下情况时，停止润色并向上游环节反馈：

无法在不猜测的前提下写出对比内容（证据包仅包含标题/摘要）
小节缺少评估锚点（笔记中无基准/指标/协议细节）
为使论证成立，需要使用超出范围的引用内容

Acceptance checklist

验收检查清单

Paragraph 1 ends with a thesis (no narration templates).
>=2 explicit contrasts, >=1 evaluation anchor, >=1 synthesis paragraph (>=2 citations), >=1 limitation.
No slide-like navigation / meta guidance / repeated evidence-policy boilerplate.
No citation-dump paragraphs; citations are embedded in claim sentences.
```
section-logic-polisher
```
and
```
writer-selfloop
```
no longer flag this file.

第一段结尾有点明论点（无叙述式模板开篇）。
包含≥2处明确对比、≥1个评估锚点、≥1个综合分析段落（引用≥2）、≥1个局限性内容。
无幻灯片式导航语 / 元指导语 / 重复的证据政策模板内容。
无引用批量罗列的段落；引用均嵌入主张句中。
```
section-logic-polisher
```
和
```
writer-selfloop
```
工具不再标记该文件存在问题。