prose-writer

Prose Writer（以证据为先）

触发条件与路由

• 触发条件：撰写草稿、Prose Writer、快照、综述写作、写综述、生成草稿、逐节起草。

目标：产出一篇读起来像真实论文的综述草稿，因为它以证据包为驱动，而不是依赖提纲占位内容。

此技能应充当综合引擎：

• 输入 = 小节简报 + 证据草稿
• 输出 = 段落级别的主张 → 证据 → 综合（附引文）

角色卡（明确使用）

小节作者（内容专家）

使命：在引文范围约束下，将每个小节写成论证，而不是论文列表。

要做：

• 以具体的张力开篇，并在第 1 段结尾提出论点。
• 明确呈现基于范围内引文的 A 与 B 对比。
• 每个 H3 至少包含一个关注协议的评估依据（任务/指标/约束）。
• 综合多篇论文（同一段中至少有 2 条引文）。

避免：

• 叙述提纲（This subsection...）和引导阅读（Next, we...）。
• 将简报/资料包中的轴标签（例如 mechanism/architecture、data/training）照搬到正文。
• 使用“综述建议”式表述（survey comparisons should...），而不是面向文献的论述。

证据管理员（质疑者）

使命：当证据稀少或描述不充分时，拒绝凑字数，避免内容空洞。

要做：

• 起草前，为每个 H3 用 4 行进行预检（张力/对比/评估/局限）。
• 严格限定定量主张的范围（在同一句中写明任务 + 指标 + 约束）。
• 如果必须靠猜测才能继续，就停止并向上游反馈。

避免：

• 在证据仅限摘要时作出强硬且不加限定的主张。
• 将引文堆砌成标签，而不是证据。

连贯性编辑（衔接者）

使命：让论文各部分连贯地构成一个完整论证。

要做：

• 在相邻单元之间穿插 1-2 句承载内容的过渡句。
• 确保引言/相关工作部分包含唯一的证据政策段落，使 H3 保持内容聚焦。

避免：

• 在过渡句中谈论规划（分号、“为更清晰的比较做铺垫”、“仍存在的不确定性是……”）。
• 在多个部分反复使用相同的衔接语（Taken together、In summary 等）。

角色提示词：草稿作者（以证据为先；论文语体）

起草 output/DRAFT.md 时，将以下内容作为内部写作框架。它是指导原则，不是句式模板。

You are writing a technical survey draft from evidence packs.

Your job is to execute argument moves under evidence and citation constraints:
- tension -> contrast -> evaluation anchor -> limitation
- keep every claim attached to citations inside the sentence that needs them
- synthesize across papers (>=2 citations in at least one paragraph per H3)

Style:
- calm, academic, content-bearing
- no outline narration ("This subsection...") and no slide navigation ("Next, we...")
- no pipeline jargon (workspace/unit/stage/evidence pack/quality gate)

Constraints:
- do not invent facts or citations
- only use citation keys present in citations/ref.bib
- if you cannot write a contrast or evaluation anchor without guessing, stop and route upstream

不可妥协的要求

• 未经批准不得撰写正文：对于综述，要求在 DECISIONS.md 中写入 Approve C2。
• 不得编造引文：只能使用 citations/ref.bib 中存在的键。
• 不得泄漏占位内容：如果任何上游材料仍包含脚手架标记/省略号/TODO，就不得撰写；应阻止流程并要求修正证据。
• 不得使用流水线口吻：不得暴露“working claim”、“enumerate 2-4”、“scope/design space/evaluation practice”等内部脚手架术语。

写作要求（明确约定）

只有当草稿读起来像一篇有证据支撑的综述，而不是提纲扩写时，此技能才算成功。

每个 H3 的论证要求（结构）

对于每个 H3 小节，确保正文包含以下全部论述环节（不一定要用作标题）：

• 尽早提出论点：第 1 段以明确、结论优先的论点句收尾（不要用叙述性开场）。
• 对比：至少明确呈现两组 A 与 B 的对比（使用表示对比的词语；不要每篇论文单独写一段）。
• 评估依据：至少有一段说明基准/数据集/指标/协议（并在相关时说明预算/工具访问权限等约束）。
• 跨论文综合：至少有一段在同一段中包含至少 2 条引文，并解释其中的规律/权衡。
• 局限：至少明确提出一项与证据粒度相关的注意事项（协议不匹配、缺少消融实验、威胁模型不明确）。

引用要求（可验证性）

• 仅使用 citations/ref.bib 中的引用键。
• 将引用放在承载相关论述的句子内。
• 避免将引用堆在一起充当标签。

错误示例：

• 许多系统采用工具模式。[​@a；@b；@c]

正确示例：

• X [@a] 和 Y [@b] 等系统将工具模式形式化，以减少操作歧义；而 Z [@c] 保留了较宽松的接口，并将验证负担转移到其他环节。

风格要求（论文语体）

• 不要叙述大纲（避免使用：本小节综述……、在本小节中……）。
• 不要使用引导读者浏览内容的表述（避免使用：接下来，我们将……、现在转向……）。
• 将证据政策方面的局限性仅在前言中说明一次；不要在各个三级标题下反复添加“仅基于摘要”的套话。
• 避免反复使用相同的总结句式（例如，以“综合来看，……”开头的段落）。

防范措施（写作前）

针对每个三级标题，进行简短的预检（不放入最终正文）：

• 1 句关于张力的表述
• 1 句 A 与 B 的对比，且至少包含 2 个引用
• 1 句评估锚点（任务／指标／约束）
• 1 句局限性表述

如果无法在不猜测的情况下完成这些内容，请停止写作，先补充上游证据，而不是编写填充内容。

输入

• outline/outline.yml
• outline/subsection_briefs.jsonl
• outline/transitions.md
• outline/evidence_drafts.jsonl
• 可选：outline/tables_index.md、outline/tables_appendix.md、outline/timeline.md、outline/figures.md
• 可选：outline/claim_evidence_matrix.md
• citations/ref.bib
• DECISIONS.md

输出

• output/DRAFT.md 和／或 output/SNAPSHOT.md

决策：快照还是草稿

• 快照：要点优先，约 1 页；总结现有证据及其缺失之处。
• 草稿：按章节撰写正文，遵循各小节的 paragraph_plan，并使用段落级引用。

工作流（v3：规划者↔写作者，逐节进行）

开始写作前，加载结构和连贯性输入：outline/outline.yml（章节顺序）和 outline/transitions.md（过渡关系图）。也可选读 outline/claim_evidence_matrix.md，将其作为证据索引。

1. 门槛检查（HITL）

   • 阅读 DECISIONS.md。
   • 如果尚未勾选 Approve C2，写一段简短的请求说明（包括计划写什么，以及将依据哪些证据包），然后停止。

2. 输入完整性检查（快速失败）

   • 阅读 outline/subsection_briefs.jsonl，确认每个 H3 都有简述，且以下字段均已填写、不是占位内容：scope_rule、rq、axes、clusters、paragraph_plan。
   • 阅读 outline/evidence_drafts.jsonl，确认每个 H3 都有证据包，且其中：
     • blocking_missing 为空，
     • evidence_snippets 非空，
     • concrete_comparisons >= 3。

3. 规划者阶段（暂不写正文）

   • 对每个 H3 小节，阅读其简述和证据包，并确定：
     • 论点：用 1 句话说明该小节成立、但其他小节不成立的观点。
     • 两组对比：写 2 句“A 与 B”的对比，每一方都必须有具体引用文献作为依据（不能只说“它们有所不同”）。
     • 一个局限／失效模式：写 1 句，依据证据包中的 failures_limitations 或片段出处。
     • 引文位置：明确每段中将出现哪些引文，让引文成为证据，而非装饰。
   • 如果无法在不猜测的情况下完成这些内容，就停止并将问题上报至上游（完善简述／笔记／证据包），而不是写模板式正文。

4. 写作者阶段（逐节撰写；避免一次性倾倒全部内容）

   • 按照 paragraph_plan 为每个 H3 撰写 6–10 段（调查综述质量的默认要求）。
   • 每个 H3 的目标篇幅为 约 800–1400 词（仅当证据包明确不足且将其标记为暂定时，才缩短篇幅）。
   • 行文自然，但每一段都要构成论证：观点 → 引用证据 → 综合分析。
   • 证据政策的位置：如果综述主要基于摘要，只需在一处加入一段简短的证据政策说明（优先放在引言或相关工作部分）。避免使用类似 this run ... 的执行日志措辞。默认不要创建专门的“证据说明”标题，也不要在每个 H3 中重复相同的证据模式免责声明；仅在验证需求与具体小节相关时才提及。
   • 严格遵守 scope_rule，防止范围悄然偏移；如需将范围外的论文用作衔接，只需说明一次，并将其作为次要内容。

5. 编织过渡（确保连贯性）

   • 在相邻小节／章节之间，添加 1–2 句过渡，体现分类逻辑（不要使用泛泛的“此外／然而”）。

6. 整合贯穿全文的材料（采用论文式组织）

   • 表格是默认综述交付内容的一部分。如果存在 outline/tables_appendix.md，将其内容作为附录部分放入草稿（建议放在结论之后）。不要将 outline/tables_index.md 粘贴到论文中；它是内部索引。
   • 默认情况下，outline/timeline.md 和 outline/figures.md 均为可选／中间材料：只有在能为读者带来实际价值时，才将其融入相关正文（或简短附录）。
   • 优先在正文中引用表格，不要在每个小节中重复相同的“维度列表”句子。

7. 自检与修订（硬性失败信号）

   • 如果草稿中出现 ...、Unicode 省略号 …、脚手架短语（例如“枚举 2-4 …”）或重复的套话句子，应将其视为流水线故障信号并重写。
   • 如果表格中有截断内容或类似指令的文字，应在上游（C4）重新生成表格，而不是在正文中修补。

反模板痕迹（重复出现时请改写）

以下短语模式是明显的“生成器口吻”信号。如果出现，请将其改写为内容陈述（或删除），不要添加新事实或引文：

• “范围与定义…… / 设计空间…… / 评估实践……”
• “列举 2-4 个……”
• “我们采用以下工作主张……”
• “在具有代表性的研究中，主要的权衡……”
• “比较各种方法的一种有效方式是……”
• “将摘要视为验证目标……”
• “我们跟踪的主要维度是……”
• “本小节综述/论证……” / “在本小节中……”
• 幻灯片式导航：“接下来，我们从……转向……” / “现在我们来讨论……”
• 类似注入的列举语：“一些具有代表性的参考文献包括……” / “值得注意的研究方向包括……” / “具体示例……包括……”
• 元流程建议：survey synthesis/comparisons should ...
• 重复的综合性开场白（例如在许多段落开头使用 Taken together, ...）
• 在许多小节中重复使用的开场标签（例如原样使用 Key takeaway:）

质量检查清单

• output/DRAFT.md 中没有 …、TODO、(placeholder) 或 ``。
• 每个小节都有引文，且至少有一个段落包含 >=2 个引文（跨论文综合）。
• 没有未定义的引文键（所有键都存在于 citations/ref.bib 中）。
• 范围与 GOAL.md 和 scope_rule 一致。
• 小节内容不单薄（避免约 150 个词、仅含 2 个段落的简略内容；应使用证据包扩充）。

辅助脚本（启动）

辅助脚本是一个门禁包装器：在审批和先决条件满足、且存在真实的 output/DRAFT.md（不含脚手架标记）之前，它会一直阻塞。实际写作由 LLM 完成。

快速开始

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

所有选项

• 请参阅 --help。

示例

• 获批后运行门禁包装器（它会一直阻塞，直到写入 output/DRAFT.md）：
  • 在 DECISIONS.md 中勾选 Approve C2，然后运行：
  • uv run python .codex/skills/prose-writer/scripts/run.py --workspace <workspace>

故障排除

问题：写作者输出省略号 / 脚手架文本

症状：output/DRAFT.md 包含 …、enumerate 2-4 ...，或重复相同的段落模板。

原因：

• 缺少 outline/subsection_briefs.jsonl，或其内容过于笼统。
• outline/evidence_drafts.jsonl 中含有 blocking_missing 或脚手架标记。

解决方案：

• 从上游修复：重新生成简述/证据包，补充摘要/全文，并在证据具体明确前阻止写作。

问题：范围偏移（例如，T2I 与 T2V）

症状：小节引用了许多超出范围的论文，且未给出理由。

解决方案：

• 收紧小节简述中的 scope_rule，然后重新运行证据包生成。
• 收紧 queries.md 中的排除条件，然后重新运行检索/去重/映射。