writer-selfloop

Writer 自循环（只修复失败项）

触发条件与路由

• 触发条件：writer self-loop、writing loop、quality gate loop、rewrite failing sections、自循环、反复改到 PASS。
• 适用场景：各节文件已存在，但 C5 为 FAIL/BLOCKED（章节内容单薄、缺少导语/前置内容、引文范围违规、生成器腔调）。

目的：让写作逐步收敛，而非重写整篇论文。

这是写作自愈循环：

默认模式：语义分诊（优先使用 LLM）

将关卡视为路由器，而不是重写所有内容的理由。

• 首先，将每项失败归类为：证据基础问题、写作执行问题、语气污染问题或引文规范问题。
• 然后，修复最早出现问题的产物（通常不是合并后的草稿）。
• 只重写失败的文件；不要反复改动已正常的章节。

如果不运行辅助脚本，也可以通过阅读 sections/*.md 和相关资料包，手动编写 output/WRITER_SELFLOOP_TODO.md，并采用相同的 PASS/FAIL 格式来执行此技能。

角色卡（明确使用）

Writing Manager（分诊与收敛）

使命：只修复失败单元，并在需要时将问题路由到上游，推动草稿收敛。

执行：

• 仅重写关卡标记的文件（每次一个）。
• 如果证据不足，将问题路由到上游，而不是用冗余文字填充。
• 重写时保持引文键和范围稳定。

避免：

• 全局重写，导致已正常的章节反复变动。
• 用泛泛的填充内容掩盖证据缺口。

Router（最早出现问题的产物）

使命：将可见的写作问题关联到最早的上游修复。

执行：

• 模板腔调 -> 局部重写（subsection-polisher / front-matter-writer / chapter-lead-writer）。
• 证据不足 -> evidence-selfloop（笔记/绑定/资料包）。

避免：

• 在资料包无法支撑内容时反复重写同一章节。

角色提示词：Writing Manager（分诊与收敛）

You are the writing manager for a survey draft.

Your job is to make the draft converge by fixing only what fails, and by routing issues to the earliest responsible artifact.

Rules:
- If a section fails because the evidence is thin or out-of-scope pressure is high, do NOT pad prose.
  Route upstream to evidence-selfloop (notes/bindings/packs) and unblock the substrate.
- If a section fails because the prose is templated (narration openers, slide navigation, repeated disclaimer spam), rewrite locally.
- Never change citation keys during rewrites; keep scope local.

Working style:
- small, auditable edits
- one failing file at a time
- every fix either (a) improves argument moves, or (b) restores paper voice

• 关卡是确定性的（检查 sections/ + sections/sections_manifest.jsonl）
• 修复是语义层面的（重写正文，以执行论证步骤并恢复论文语气）

输入

• sections/sections_manifest.jsonl（预期文件 + 允许使用的引文）
• sections/*.md（实际的正文单元）
• outline/writer_context_packs.jsonl（优先使用各 H3 对应的资料包）
• outline/evidence_bindings.jsonl
• citations/ref.bib

可选路由上下文：

• output/EVIDENCE_SELFLOOP_TODO.md（如果已知存在证据缺口）
• outline/subsection_briefs.jsonl、outline/chapter_briefs.jsonl

输出

• output/WRITER_SELFLOOP_TODO.md（报告类；始终写入）

工作流

1. 运行门禁

• 运行作者自循环脚本（见下方的脚本部分）。该脚本会读取 sections/sections_manifest.jsonl 和实际的 sections/*.md 文件。

2. 阅读 TODO 报告

• 打开 output/WRITER_SELFLOOP_TODO.md，找出未通过检查的文件路径。
• 如果同一个 H3 中重复出现证据级句子，将其视为阻塞问题；修复支持材料的选择，或删除重复内容，同时不改变引文范围。
• 对于每个未通过检查的 H3，从 outline/writer_context_packs.jsonl 加载对应的 pack。
• 如果缺少 pack，或需要确认范围，则查阅 outline/subsection_briefs.jsonl；对于章节级上下文（引入语和贯穿主线），则查阅 outline/chapter_briefs.jsonl。

3. 分类处理（写作还是证据）

遇到以下情况时，上游处理（运行 evidence-selfloop）：

• output/EVIDENCE_SELFLOOP_TODO.md 已指出同一小节缺少锚点或比较
• outline/writer_context_packs.jsonl 中的 pack 过于单薄，无法在不猜测的情况下支撑论证推进
• 你反复想要引用 outline/evidence_bindings.jsonl 范围之外的内容

遇到以下情况时，在本地重写：

• pack 内容充足，但行文像模板（叙述式开头、幻灯片式导航、重复的衔接语）
• 小节有内容，但缺少论点、对比、评价锚点或局限性

4. 根据未通过检查的文件类型使用相应的操作指南

• 前置部分（sections/abstract.md、用于引言/相关工作的 sections/S<sec_id>.md、sections/discussion.md、sections/conclusion.md）：使用 front-matter-writer。
• 章节引入语（sections/S<sec_id>_lead.md）：使用 chapter-lead-writer。
• H3 正文（sections/S<sub_id>.md）：使用 subsection-writer（起草）或 subsection-polisher（本地修复）。

5. 保持范围和引文稳定

• 保持引文键不变，并根据 citations/ref.bib 对其进行验证。
• 按照 outline/evidence_bindings.jsonl 确定范围（优先采用小节级范围）。

6. 重新运行门禁，直至通过

通过后（合并感知的语气安全检查）：

• 依次执行 style-harmonizer -> opener-variator -> section-logic-polisher -> paragraph-curator -> evaluation-anchor-checker -> 最终的 argument-selfloop 快照 -> 可选的 transition-weaver -> section-merger -> post-merge-voice-gate。
• 如果 post-merge-voice-gate 因 source: transitions 未通过，则说明已明确启用过渡语插入；修复 outline/transitions.md 并重新合并。

通过后（所有 survey-family 配置文件都必须进行的文风检查）：

• 打开 output/WRITER_SELFLOOP_TODO.md 并阅读 ## Style Smells。
• 对列出的 sections/*.md 文件运行 style-harmonizer。
• 如果它标记了开头节奏或 overview 叙述问题，则对列出的文件运行 opener-variator。
• 如果它标记了基于数量的局限性段落（例如 Two limitations ...），则对列出的文件运行 limitation-weaver。
• 完成逻辑调整和段落精简后，对已定稿的 H3 文件运行 evaluation-anchor-checker，然后重新生成论证/清单快照。
• 保持含义和引文不变；这属于表层改写，而非新增内容。

如何修复未通过检查的 H3（语义处理方案）

• 使用 pack 中的 tension_statement 和 thesis 重写第 1 段（以论点收尾）。
• 使用 comparison_cards 撰写明确的 A 与 B 对比句。
• 使用 evaluation_anchor_minimal / protocol snippets 补充任务、指标和约束的背景信息。
• 使用局限性提示补充真实的注意事项（而非套话）。

论文语气修正（高影响、低风险）

叙述式开场 -> 内容主张：

• 不佳：This subsection surveys ...
• 更好：先用一句话提出张力／决策／视角，然后在第 1 段末尾落到论点。

幻灯片式导航 -> 论证衔接：

• 不佳：Next, we move from X to Y.
• 更好：Having established X, we can now examine how Y changes the trade-offs under comparable protocols.

元话语“综述应当” -> 面向文献的观察：

• 不佳：Therefore, survey comparisons should ...
• 更好：Across reported protocols, ... varies, which makes ... fragile unless ...

免责声明泛滥 -> 一段统一政策说明，仅在必要时添加局部限定：

• 在前置部分保留一次证据政策说明；删除 H3 中重复的“仅基于摘要”套话。

停止条件（不该改写的情况）

遇到以下情况时停止并向上游反馈：

• 如果不靠猜测就无法写出对比或评估锚点
• 如果素材包缺少支撑该小节核心主张所需的基准、指标或协议详情
• 如果修复一个 H3 总会迫使你添加超出范围的引用

失败代码 -> 路由（如何解读检查结果）

写作检查会输出简短的问题代码。将它们视为路由指示，不要试图用冗长文字掩盖证据缺失。

先对失败进行分类：

• 证据基础：素材包／锚点／对比过于薄弱，无法在不猜测的情况下完成论证。路由至上游（evidence-selfloop）。
• 写作执行：素材包足够丰富，但本节未完成论证动作（论点／对比／评估／局限）。在本地改写。
• 语气污染：带有叙述／幻灯片／流水线语气。在本地改写（开场 + 衔接），不要改动引用。
• 引用规范：键未定义／范围压力。修正引用／绑定，或改写以符合范围；不要添加新键。

快速对照（常见代码）：

• missing_sections_manifest、empty_sections_manifest、sections_missing_files：运行 subsection-writer（创建缺失文件 + 刷新清单）。
• sections_h3_has_headings：移除标题；H3 正文只能包含正文。
• sections_intro_*、sections_related_work_*：通过 front-matter-writer 改写前置部分（紧凑定位 + 一条方法说明）。
• sections_h3_too_few_paragraphs、sections_h3_too_short：如果素材包内容丰富，则通过展开对比 + 评估锚点 + 局限来扩写；如果素材包内容单薄，则路由至 evidence-selfloop。
• sections_h3_missing_contrast：使用 comparison_cards 添加明确的 A 与 B 对比；如果缺少卡片，则将简报／素材包路由至 evidence-selfloop。
• sections_h3_missing_eval_anchor、sections_h3_missing_cited_numeric：在同一段中补充最简协议背景（任务／指标／约束）；如果未知，则路由至上游或弱化主张。
• sections_h3_missing_limitation：添加针对该小节的局限；如果素材包中不存在，则路由至上游。
• sections_h3_narration_template_opener、sections_h3_slide_narration、sections_contains_pipeline_voice：将开场／衔接改写为论文语气（不作导航式评论）。
• sections_h3_evidence_policy_disclaimer_spam：删除重复内容；在前置部分保留一次证据政策说明。
• sections_cites_missing_in_bib：重新运行 citation-verifier（不要编造键）。
• sections_cites_outside_mapping：改写以符合范围，或修正映射／绑定（C2/C4）并重建素材包；不要在合并后的草稿中打补丁。
• sections_h3_sparse_citations：如果范围允许，通过 citation-diversifier 规划新增引用，再通过 citation-injector 应用；如果范围过于严格，则在上游扩展映射／绑定。

脚本（可选；确定性检查）

快速开始

• uv run python .codex/skills/writer-selfloop/scripts/run.py --workspace <workspace>

所有选项

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

示例

• 为未通过检查的 sections/*.md 生成可执行的 TODO 列表：
  • uv run python .codex/skills/writer-selfloop/scripts/run.py --workspace <workspace>