subsection-briefs

小节简介

触发条件与路由

• 触发词：subsection briefs、writing cards、intent cards、H3 briefs、scope_rule、axes、clusters、写作意图卡、小节卡片、段落计划。

outline/subsection_briefs.refined.ok 仅当标记的更新时间晚于简介、声明的输入、领域包和生成器时，才会冻结已审阅的简介。重新生成并备份前，会移除过期标记。

从大纲、映射和论文笔记中，确定性地构建 H3 简介卡片。

兼容模式已启用：此技能保留当前的 outline/subsection_briefs.jsonl 字段约定和段落计划结构，同时将短语和领域逻辑移入 references/ 和 assets/。

快速使用

• 将 scripts/run.py 用作确定性物化器。
• 输出必须不包含散文：仅包含小节范围内的计划、轴、集群和衔接线索。
• 保持与下游 transition-weaver、writer-context-pack 和 subsection-writer 的现有兼容性。

加载顺序

始终阅读：

• references/overview.md

按任务阅读：

• 如果 thesis 显得重复或容易照搬，请阅读 references/thesis_patterns.md。
• 如果 tension_statement 太笼统，请阅读 references/tension_patterns.md。
• 如果轴较弱或偏向特定领域，请阅读 references/axis_catalog_generic.md 和 references/axis_catalog_llm_agents.md。
• 如果衔接线索显得平淡，请阅读 references/bridge_terms.md。
• 如需校准，请阅读 references/examples_good.md。

机器可读资源：

• assets/phrase_packs/thesis_patterns.json
• assets/phrase_packs/bridge_contrast.json
• assets/domain_packs/generic.json
• assets/domain_packs/llm_agents.json
• assets/domain_packs/embodied_ai.json
• assets/domain_packs/rag_evaluation.json
• assets/domain_packs/text_to_image.json

脚本会先加载这些包；如果问题出在措辞、领域路由、轴清单、集群纯度或词汇衔接覆盖范围上，请先修改这些包，再改 Python。

输入

• outline/outline.yml
• outline/mapping.tsv
• papers/paper_notes.jsonl
• 可选：GOAL.md
• 可选：outline/claim_evidence_matrix.md

输出

• outline/subsection_briefs.jsonl

必需的记录结构保持兼容：

• 标识信息：sub_id、title、section_id、section_title
• 规划核心：rq、thesis、scope_rule、axes、bridge_terms、contrast_hook、tension_statement
• 证据线索：evaluation_anchor_minimal、required_evidence_fields、clusters
• 执行计划：paragraph_plan、evidence_level_summary、generated_at

run.py 应执行的操作

• 读取大纲、映射和笔记。
• 根据大纲项目规范化小节种子。
• 从 assets/ 加载论点、张力和领域轴包。
• 按现有约定生成稳定的 JSONL 记录。

run.py 不应执行的操作

• 不要编造论文、引文或主张。
• 不要输出面向读者的叙述性散文。
• 如果资源包可以承载领域专用句式模板，就不要将其硬编码。

阻止 / 重新路由

• 如果缺少大纲、映射或笔记，请停止。
• 如果证据薄弱，请让 thesis / tension_statement 保持谨慎，并交由下游证据技能加强小节内容。
• 如果对比集群合并成重叠的论文池，请在写作前重新路由：移除衔接论文后，每一侧仍应至少保留 2 篇独有论文。
• 使用 bridge_terms 提取具体的词汇线索，供后续证据和排序阶段匹配（OOD、sim-to-real、world model、failure detector、特定基准系列），而不只是通用轴名称。
• 如果映射集规模已足以支持互不相交的集群，优先使用领域包中的 cluster_rules，而不是临时采用重叠规则。
• 不要通过编造更具体的轴或更强的主张来“修复”证据薄弱的问题。

执行说明

在兼容模式下运行时，scripts/run.py 目前会读取：

• outline/outline.yml，用于获取章节/小节结构
• outline/mapping.tsv，用于获取论文到小节的覆盖关系
• papers/paper_notes.jsonl，用于获取结构化证据
• GOAL.md，用于获取主题/领域线索
• outline/claim_evidence_matrix.md，作为可选的补充上下文（如果存在）

脚本

快速开始

• uv run python .codex/skills/subsection-briefs/scripts/run.py --workspace <workspace>

所有选项

• --workspace <dir>
• --unit-id <id>
• --inputs <a;b;...>
• --outputs <a;b;...>
• --checkpoint <C*>

示例

• uv run python .codex/skills/subsection-briefs/scripts/run.py --workspace <workspace>

故障排除

• 如果选中了错误的领域包，请检查 GOAL.md 和资源包，再考虑修改脚本。
• 如果简报听起来过于笼统，请调整措辞包/领域包，而不是添加更多 Python 文字说明。
• 如果 papers/paper_notes.jsonl 内容单薄，请改为进行笔记提取，而不是凭空编造分析维度。