transition-weaver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Transition Weaver (LLM-first; NO NEW FACTS)

Transition Weaver（优先使用LLM；禁止添加新事实）

Purpose: produce a small, low-risk “transition map” so adjacent subsections do not read like islands.

This skill is intentionally LLM-first:

you write
```
outline/transitions.md
```
as paper-voice content sentences
the helper script is validation-only (it never generates prose)

Transitions should answer:

what the previous unit established
what gap/tension remains
why the next unit follows

用途：生成一份简洁、低风险的“过渡映射表”，使相邻小节内容不会显得孤立。

本技能特意采用LLM优先的设计：

你需要以论文口吻撰写
```
outline/transitions.md
```
中的过渡语句
辅助脚本仅用于验证（绝不会生成散文内容）

过渡内容需要回答以下问题：

上一部分内容确立了什么
仍存在哪些空白/矛盾点
下一部分内容为何需要跟进

Injection contract (treat transitions as draft text)

嵌入约定（将过渡内容视为草稿文本）

outline/transitions.md

is not planning notes:

section-merger

injects it into

output/DRAFT.md

. So each transition line must be safe to read as paper prose.

Format contract (for merge insertion):

Only lines matching
```
- 3.1 -> 3.2: <text>
```
are inserted by default (within-chapter H3 -> next H3).
Keep
```
<text>
```
as one sentence without list formatting.

Notes:

Use the ASCII arrow
```
->
```
(not a unicode arrow) to avoid invisible/control-character encoding issues.
```
section-merger
```
accepts both
```
->
```
and
```
→
```
for backward compatibility, but
```
->
```
is the preferred contract.

Hard rules:

Write the transition sentence as final prose: content-bearing, not process-bearing.
No planner-talk openers: avoid stems like "To keep ...", "The remaining uncertainty is ...", "setting up a cleaner ...".
No slash-list axis labels (A / B / C; planning/memory). Rewrite using natural prose.
Keep it short: one sentence is preferred; rarely two.
Avoid semicolon-heavy multi-clause construction notes.

Rewrite triggers (if you see these, rewrite):

"To keep ..." / "We next focus on ..." / "The remaining uncertainty is ..."
"as the comparison lens" / "reference point" / "to make the next trade-offs easier to interpret"

outline/transitions.md

并非规划笔记：

section-merger

会将其嵌入到

output/DRAFT.md

中。因此每条过渡语句必须可以直接作为论文内容阅读。

合并插入格式约定：

默认仅插入符合
```
- 3.1 -> 3.2: <text>
```
格式的行（同一章节内H3到下一个H3的过渡）。
```
<text>
```
部分需为单个句子，不得使用列表格式。

注意事项：

使用ASCII箭头
```
->
```
（而非Unicode箭头），避免出现不可见字符或编码问题。
为了向后兼容，
```
section-merger
```
同时支持
```
->
```
和
```
→
```
，但推荐使用
```
->
```
作为标准约定。

硬性规则：

过渡语句需以最终散文形式撰写：承载内容，而非记录流程。
避免使用规划类开场白：不要以“为保持……”“剩余的不确定性是……”“为构建更清晰的……”这类语句开头。
避免使用斜杠分隔的轴标签（如A / B / C；规划/记忆类表述），改用自然散文重写。
保持语句简短：优先使用单句，最多两句。
避免使用包含多个从句的分号结构。

重写触发条件（若出现以下内容，需重写）：

“为保持……” / “接下来我们聚焦于……” / “剩余的不确定性是……”
“作为对比视角” / “参考点” / “使后续权衡更易解读”

Role prompt: Linker (coherence without narration)

角色提示：衔接者（无叙事的连贯性构建）

text

You are the coherence linker for a survey.

Your job is to write short, content-bearing transitions between adjacent subsections:
- restate what was established (one clause)
- name the remaining tension/gap (one clause)
- justify why the next subsection is the right lens (one clause)

Style:
- argument bridge, not navigation
- no “Now we discuss / Next we move / In this section…”
- no semicolon planning notes

Constraints:
- NO NEW FACTS
- NO citations
- only reuse handles that already exist (titles, RQs, bridge_terms)

Style targets (paper-like, still NO NEW FACTS):

Prefer argument bridges: content-bearing sentences, not outline narration.
Keep it short (often 1 sentence).
Avoid title narration once merged: do not write “From Section A to Section B”.
Avoid “Now we discuss / Next we introduce / In this section we ...”.

CRITICAL: Transitions must be real content sentences, NOT construction notes.

Bad: “After X, Y makes the bridge explicit via …; …; setting up a cleaner A-vs-B comparison.”
Good: “While loop design determines what actions are possible, tool interfaces define how those actions are grounded in executable APIs and orchestration policies.”

Also avoid (reads like axis/planning notes once merged):

Slash-list axis labels (e.g.,
```
A/B/C
```
,
```
planning/memory
```
); rewrite using natural prose (
```
and
```
/
```
or
```
).

text

You are the coherence linker for a survey.

Your job is to write short, content-bearing transitions between adjacent subsections:
- restate what was established (one clause)
- name the remaining tension/gap (one clause)
- justify why the next subsection is the right lens (one clause)

Style:
- argument bridge, not navigation
- no “Now we discuss / Next we move / In this section…”
- no semicolon planning notes

Constraints:
- NO NEW FACTS
- NO citations
- only reuse handles that already exist (titles, RQs, bridge_terms)

风格目标（类论文风格，仍禁止添加新事实）：

优先使用论证式衔接：承载内容的语句，而非大纲叙事。
保持简短（通常为单句）。
合并后避免标题叙事：不要写“从A节到B节”。
避免使用“现在我们讨论/接下来我们介绍/本节我们将……”这类表述。

关键要求：过渡内容必须是真实的承载性语句，而非构建笔记。

错误示例：“在X之后，Y通过……明确构建衔接；……；为A与B的对比搭建更清晰的框架。”
正确示例：“虽然循环设计决定了可执行的操作类型，但工具接口定义了这些操作如何在可执行API和编排策略中落地。”

同时避免（合并后读起来像轴/规划笔记的内容）：

斜杠分隔的轴标签（如
```
A/B/C
```
、
```
planning/memory
```
）；改用自然散文（
```
and
```
/
```
or
```
）重写。

Inputs

输入文件

```
outline/outline.yml
```
(ordering + titles)

outline/subsection_briefs.jsonl

(expects

rq

and optional

bridge_terms

contrast_hook

)

```
outline/outline.yml
```
（内容顺序及标题）

outline/subsection_briefs.jsonl

（包含

rq

字段，可选

bridge_terms

contrast_hook

字段）

Output

输出文件

```
outline/transitions.md
```
(used by
```
section-merger
```
; keep paper voice)

```
outline/transitions.md
```
（供
```
section-merger
```
使用；需采用论文口吻）

Workflow (NO NEW FACTS)

工作流程（禁止添加新事实）

Read
```
outline/outline.yml
```
to determine adjacency (which H3 follows which).
Read
```
outline/subsection_briefs.jsonl
```
to extract each subsection’s
```
rq
```
and any bridge handles (
```
bridge_terms
```
,
```
contrast_hook
```
).
For each boundary, write 1–2 transition sentences:

no new facts
no citations
no explicit “we organize this section as …” meta narration
no placeholders (
```
TODO
```
,
```
…
```
,
```

```
)

Write
```
outline/transitions.md
```
.

读取
```
outline/outline.yml
```
以确定内容的相邻关系（哪个H3紧跟在哪个之后）。
读取
```
outline/subsection_briefs.jsonl
```
以提取每个小节的
```
rq
```
及所有衔接标识（
```
bridge_terms
```
、
```
contrast_hook
```
）。
为每个内容边界撰写1-2句过渡语句：

不得添加新事实
不得添加引用
不得使用“我们将本节组织为……”这类明确的元叙事表述
不得使用占位符（
```
TODO
```
、
```
…
```
、
```

```
）

写入
```
outline/transitions.md
```
文件。

Role cards (use explicitly)

角色卡片（需明确使用）

Linker (argument bridge)

衔接者（论证式衔接）

Mission: write short, content-bearing transitions without narration.

Do:

Restate what was established (one clause).
Name the remaining tension/gap (one clause).
Justify why the next unit follows (one clause).

Avoid:

Title narration ("From X to Y") and slide navigation ("Now we turn").
Semicolon planning notes or meta commentary.

任务：撰写简短、承载内容的过渡语句，无叙事性表述。

需执行：

重述上一部分确立的内容（一个分句）。
指出仍存在的矛盾/空白（一个分句）。
说明下一部分内容为何合适（一个分句）。

需避免：

标题叙事（“从X到Y”）和幻灯片导航式表述（“现在我们转向”）。
分号分隔的规划笔记或元评论。

Skeptic (template killer)

质疑者（模板清除者）

Mission: delete anything that reads like construction notes.

Do:

Remove generic transitions that could fit any subsection.
Force subsection-specific nouns from titles/RQs/bridge terms.

Avoid:

Smuggling new facts into transitions.

任务：删除所有读起来像构建笔记的内容。

需执行：

删除可适用于任意小节的通用过渡内容。
强制使用来自标题、RQs、衔接术语的小节专属名词。

需避免：

在过渡内容中偷偷加入新事实。

Script (optional; validation only)

脚本（可选；仅用于验证）

You usually do not run this manually; it exists so a pipeline runner can deterministically validate the artifact.

通常无需手动运行该脚本；它用于让流水线执行者可确定性地验证产物。

Quick Start

快速开始

python .codex/skills/transition-weaver/scripts/run.py --workspace workspaces/<ws>

python .codex/skills/transition-weaver/scripts/run.py --workspace workspaces/<ws>

All Options

所有选项

```
--workspace <dir>
```
: workspace root
```
--unit-id <U###>
```
: unit id (optional; for logs)
```
--inputs <semicolon-separated>
```
: override inputs (rare; prefer defaults)

--outputs <semicolon-separated>

: override outputs (rare; default validates

outline/transitions.md

)

```
--checkpoint <C#>
```
: checkpoint id (optional; for logs)

```
--workspace <dir>
```
：工作区根目录
```
--unit-id <U###>
```
：单元ID（可选；用于日志）
```
--inputs <semicolon-separated>
```
：覆盖输入文件（罕见；优先使用默认值）

--outputs <semicolon-separated>

：覆盖输出文件（罕见；默认验证

outline/transitions.md

）

```
--checkpoint <C#>
```
：检查点ID（可选；用于日志）

Examples

示例

Validate after you write

outline/transitions.md

python .codex/skills/transition-weaver/scripts/run.py --workspace workspaces/<ws>

在你撰写完

outline/transitions.md

后进行验证：

python .codex/skills/transition-weaver/scripts/run.py --workspace workspaces/<ws>

Troubleshooting

故障排除

Issue: transitions read like templates

问题：过渡内容读起来像模板

Fix:

Ensure subsection briefs include subsection-specific bridge signals (
```
bridge_terms
```
/
```
contrast_hook
```
).
Rewrite the transitions to mention those handles (as content, not as axis-label lists).

修复方法：

确保小节摘要包含小节专属的衔接信号（
```
bridge_terms
```
/
```
contrast_hook
```
）。
重写过渡内容，将这些标识作为内容提及（而非轴标签列表）。

Note: between-H2 transitions

注意：H2之间的过渡

By default,

section-merger

inserts within-chapter H3->H3 transitions only (more paper-like). If you want between-H2 transitions inserted too, create

outline/transitions.insert_h2.ok

in the workspace.

默认情况下，

section-merger

仅插入同一章节内H3->H3的过渡内容（更符合论文风格）。如果你也希望插入H2之间的过渡内容，请在工作区中创建

outline/transitions.insert_h2.ok

文件。