section-logic-polisher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Section Logic Polisher (thesis + argument bridges)

Section Logic Polisher（论点+论证过渡）

Purpose: close the main “paper feel” gap that remains even when a subsection is long and citation-dense:

missing/weak thesis (paragraph 1 never commits to a claim)
weak inter-paragraph flow (paragraph islands; no content-bearing bridges)

This is a local, per-H3 polish step that happens after drafting and before merging.

Note: if the main problem is redundancy/overgrowth (sections only get longer), use

paragraph-curator

for a select->fuse pass. This skill stays focused on thesis + bridges.

目的：填补即使子章节篇幅较长、引用密集时仍存在的「论文质感」缺口：

论点缺失或薄弱（第一段未明确提出主张）
段落间衔接性差（段落孤岛；无承载实质内容的过渡句）

这是一个本地化的、针对单个H3章节的润色步骤，完成于草稿撰写后、章节合并前。

注意：如果主要问题是内容冗余/膨胀（章节篇幅只增不减），请使用

paragraph-curator

进行筛选融合处理。本工具专注于论点优化与段落衔接。

What this skill blocks on (and what it does not)

本工具的阻塞项与非阻塞项

Blocking (must fix):

paragraph 1 lacks an explicit thesis / takeaway (a content claim)

Non-blocking (diagnostic only):

connector word counts (e.g., “moreover/however/therefore”). Counts are a proxy for paragraph islands, but forcing them as a quota often creates “generator cadence” (paragraph-initial adverbs). Treat these stats as signals, not goals.

阻塞项（必须修复）：

第一段缺乏明确的论点/核心结论（实质性主张）

非阻塞项（仅用于诊断）：

连接词使用数量（例如「moreover/however/therefore」）。这些数量仅作为段落孤岛的参考指标，但若强行将其作为硬性配额，往往会导致「生成式语气」（段落开头使用副词）。请将这些统计数据视为信号，而非目标。

Role prompt: Logic Editor (argument flow)

角色提示：Logic Editor（论证连贯性）

text

You are the logic editor for one survey subsection.

Your job is to make the subsection read like a single argument:
- paragraph 1 commits to a clear thesis (content claim)
- each paragraph has an explicit logical relation to the previous one
- bridges are content-bearing (contrast/causal/implication), not slide narration

Constraints:
- do not add new citations
- do not change citation keys
- do not invent facts

Editing lens:
- if a paragraph does not advance the argument (claim/contrast/eval/limitation), compress or delete it
- if a transition is empty, rewrite it as a content-bearing bridge

text

You are the logic editor for one survey subsection.

Your job is to make the subsection read like a single argument:
- paragraph 1 commits to a clear thesis (content claim)
- each paragraph has an explicit logical relation to the previous one
- bridges are content-bearing (contrast/causal/implication), not slide narration

Constraints:
- do not add new citations
- do not change citation keys
- do not invent facts

Editing lens:
- if a paragraph does not advance the argument (claim/contrast/eval/limitation), compress or delete it
- if a transition is empty, rewrite it as a content-bearing bridge

Inputs

输入项

```
sections/
```
(expects H3 body files like
```
S<sec>_.md
```
)

outline/subsection_briefs.jsonl

(use

thesis

paragraph_plan[].connector_phrase

as intent)

Optional:
```
outline/writer_context_packs.jsonl
```
(preferred; has trimmed anchors/comparisons +
```
must_use
```
)

```
sections/
```
（预期包含H3章节正文文件，格式如
```
S<sec>_.md
```
）

outline/subsection_briefs.jsonl

（使用其中的

thesis

paragraph_plan[].connector_phrase

作为意图参考）

可选：
```
outline/writer_context_packs.jsonl
```
（优先使用；包含精简的锚点/对比内容 +
```
must_use
```
强制要求项）

Outputs

输出项

```
output/SECTION_LOGIC_REPORT.md
```
(PASS/FAIL for thesis; connector stats shown for diagnosis)

Manual / LLM-first (in place):

Update the H3 body files under
```
sections/
```
(e.g.,
```
sections/S<sec>_.md
```
) to fix thesis/bridges (no new citations; keep keys stable)

```
output/SECTION_LOGIC_REPORT.md
```
（包含论点检查的通过/失败状态；连接词统计数据用于诊断）

手动/LLM优先修改（原地修改）：

更新
```
sections/
```
下的H3章节正文文件（例如
```
sections/S<sec>_.md
```
），以修复论点/衔接问题（不得添加新引用；保留引用标识稳定）

Workflow (self-loop)

工作流（自循环）

Run the checker script to surface the exact failing files.
For each failing H3 file:

Work on the concrete H3 body file (pattern):
```
sections/S<sec>_.md
```
Use
```
outline/subsection_briefs.jsonl
```
as the source of truth for the subsection thesis and paragraph-plan intent.
If available, prefer
```
outline/writer_context_packs.jsonl
```
to stay aligned with
```
must_use
```
anchors/constraints (no new cites).
Thesis (blocking)
- Make paragraph 1 end with a conclusion-first thesis sentence.
- Prefer a content claim, not meta narration. Avoid repetitive openers like
```
This subsection argues/surveys ...
```
  .
- Minimal shape (3 sentences; paraphrase, don’t copy):
  1. claim / tension
  2. why it matters (protocol/evaluation relevance)
  3. how the subsection will resolve it (what contrasts/anchors it will use)
Flow (fix only when needed)
- Add 1–2 short bridges where paragraphs feel disconnected.
- Prefer subject-first sentences and mid-sentence glue (because/while/which) over paragraph-start adverbs.
- Avoid PPT navigation (
```
Next, we ...
```
  ,
```
We now turn to ...
```
  ).

Rerun the checker until

output/SECTION_LOGIC_REPORT.md

is PASS, then proceed to

transition-weaver

and

section-merger

运行检查脚本，定位具体的未通过文件。
针对每个未通过的H3文件：

处理具体的H3章节正文文件（格式）：
```
sections/S<sec>_.md
```
将
```
outline/subsection_briefs.jsonl
```
作为子章节论点和段落计划意图的权威来源。
如果有
```
outline/writer_context_packs.jsonl
```
，优先使用以确保符合
```
must_use
```
锚点/约束（不得添加新引用）。
论点优化（阻塞项）
- 确保第一段结尾有一个结论先行的论点句。
- 优先使用实质性主张，而非元叙事。避免重复的开头，如
```
This subsection argues/surveys ...
```
  。
- 最简结构（3句话；改写而非复制）：
  1. 主张/矛盾点
  2. 重要性（与协议/评估的相关性）
  3. 子章节的解决方式（将使用的对比/锚点）
衔接优化（仅在必要时修复）
- 在段落间衔接不畅的地方添加1-2句简短的过渡句。
- 优先使用主语先行的句子和句中衔接词（because/while/which），而非段落开头的副词。
- 避免PPT式导航语（如
```
Next, we ...
```
  、
```
We now turn to ...
```
  ）。

重新运行检查脚本，直到
```
output/SECTION_LOGIC_REPORT.md
```
显示「- Status: PASS」，然后再运行
```
transition-weaver
```
和
```
section-merger
```
。

Examples

示例

Thesis signal (paragraph 1)

论点示例（第一段）

Bad (topic setup only):

Tool interfaces vary across agent systems, and many recent works explore different designs.

Better (conclusion-first claim):

A central tension in tool interfaces is balancing expressivity with verifiability; as a result, interface contracts often determine which evaluation claims transfer across environments.

Bad (meta narration):

This subsection argues that memory is important for agents.

Better (content claim):

Memory designs trade off retrieval reliability against write-time contamination, and this trade-off shows up as distinct failure modes under fixed evaluation protocols.

反面示例（仅话题引入）：

Tool interfaces vary across agent systems, and many recent works explore different designs.

正面示例（结论先行的主张）：

A central tension in tool interfaces is balancing expressivity with verifiability; as a result, interface contracts often determine which evaluation claims transfer across environments.

反面示例（元叙事）：

This subsection argues that memory is important for agents.

正面示例（实质性主张）：

Memory designs trade off retrieval reliability against write-time contamination, and this trade-off shows up as distinct failure modes under fixed evaluation protocols.

Bridges (avoid paragraph islands)

衔接示例（避免段落孤岛）

Bad (no relation):

```
X does ...
```
(para 2)
```
Y does ...
```
(para 3)

Better (explicit tie):

Whereas X optimizes for <axis>, Y shifts the bottleneck to <axis>; under fixed budgets, this changes whether the reported gains reflect better planning or simply more expensive search.

反面示例（无关联）：

```
X does ...
```
（第二段）
```
Y does ...
```
（第三段）

正面示例（明确关联）：

Whereas X optimizes for <axis>, Y shifts the bottleneck to <axis>; under fixed budgets, this changes whether the reported gains reflect better planning or simply more expensive search.

Done criteria

完成标准

output/SECTION_LOGIC_REPORT.md

shows

- Status: PASS

No section file contains placeholders (
```
TODO
```
/
```
…
```
/
```
...
```
) or outline meta markers (
```
Intent:
```
/
```
RQ:
```
/
```
Evidence needs:
```
)
Every H3 has a clear paragraph-1 thesis; bridges are added only where flow is actually broken

```
output/SECTION_LOGIC_REPORT.md
```
显示「- Status: PASS」
所有章节文件中无占位符（
```
TODO
```
/
```
…
```
/
```
...
```
）或大纲元标记（
```
Intent:
```
/
```
RQ:
```
/
```
Evidence needs:
```
）
每个H3章节的第一段都有清晰的论点；仅在衔接确实不畅的地方添加过渡句

Script

脚本

Quick Start

快速开始

python .codex/skills/section-logic-polisher/scripts/run.py --workspace workspaces/<ws>

Notes:

The script is a checker; it does not rewrite prose.
Connector stats are printed for diagnosis. Do not “write to the counter”; write to the argument.

python .codex/skills/section-logic-polisher/scripts/run.py --workspace workspaces/<ws>

注意：

本脚本仅为检查工具；不会自动重写文本。
连接词统计数据仅用于诊断。请勿「为了凑数而添加连接词」，应围绕论证逻辑进行写作。

All Options

所有可选参数

```
--workspace <dir>
```
```
--unit-id <U###>
```
```
--inputs <semicolon-separated>
```
```
--outputs <semicolon-separated>
```
```
--checkpoint <C#>
```

```
--workspace <dir>
```
```
--unit-id <U###>
```
```
--inputs <semicolon-separated>
```
```
--outputs <semicolon-separated>
```
```
--checkpoint <C#>
```

Examples

示例命令

Default run:

python .codex/skills/section-logic-polisher/scripts/run.py --workspace workspaces/<ws>

Explicit output path (rare override; prefer defaults):

python .codex/skills/section-logic-polisher/scripts/run.py --workspace workspaces/<ws> --outputs output/SECTION_LOGIC_REPORT.md

默认运行：

python .codex/skills/section-logic-polisher/scripts/run.py --workspace workspaces/<ws>

指定输出路径（罕见场景；优先使用默认路径）：

python .codex/skills/section-logic-polisher/scripts/run.py --workspace workspaces/<ws> --outputs output/SECTION_LOGIC_REPORT.md