Back to Details

chapter-briefs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Chapter Briefs (H2 writing cards) [NO PROSE]

章节写作简报（H2写作卡片）【禁止写成散文】

Purpose: turn each H2 chapter that contains H3 subsections into a chapter-level writing card so the writer can:
  • add a chapter lead paragraph block (coherence)
  • keep a consistent comparison axis across the chapter
  • avoid “8 small islands” where every H3 restarts from scratch
This artifact is internal intent, not reader-facing prose.
Why this matters for writing quality:
  • Chapter briefs prevent the "paragraph island" failure mode: without a throughline, each H3 restarts and repeats openers.
  • Treat 
    throughline
    and 
    lead_paragraph_plan
    as decision constraints, not copyable sentences.
目的：将每个包含H3子小节的H2章节转换为章节级写作卡片，以便作者：
  • 添加章节引言段落模块（保证连贯性）
  • 保持整个章节的对比维度一致
  • 避免出现“8个孤立小模块”的情况，即每个H3小节都从头开始叙述
该文档是内部意图说明，并非面向读者的正式文稿。
为何这对写作质量至关重要：
  • 章节写作简报可避免“段落孤岛”问题：若没有贯穿全文的主线，每个H3小节都会重复开篇内容。
  • 将
    throughline
    （贯穿主线）和
    lead_paragraph_plan
    （引言段落规划）视为决策约束，而非可直接复制的句子。

Inputs

输入文件

  • outline/outline.yml
  • outline/subsection_briefs.jsonl
  • Optional: 
    GOAL.md
  • outline/outline.yml
  • outline/subsection_briefs.jsonl
  • 可选：
    GOAL.md

Outputs

输出文件

  • outline/chapter_briefs.jsonl
  • outline/chapter_briefs.jsonl

Output format (
outline/chapter_briefs.jsonl
)

输出格式（
outline/chapter_briefs.jsonl
）

JSONL (one object per H2 chapter that has H3 subsections).
Required fields:
  • section_id
    , 
    section_title
  • subsections
    (list of 
    {sub_id,title}
    in outline order)
  • synthesis_mode
    (one of: 
    clusters
    , 
    timeline
    , 
    tradeoff_matrix
    , 
    case_study
    , 
    tension_resolution
    )
  • synthesis_preview
    (1–2 bullets; how the chapter will synthesize across H3 without template-y “Taken together…”)
  • throughline
    (3–6 bullets)
  • key_contrasts
    (2–6 bullets; pull from each H3 
    contrast_hook
    when available)
  • lead_paragraph_plan
    (2–3 bullets; plan only, not prose)
    • Each bullet should be chapter-specific and mention concrete handles (axes / contrast hooks / evaluation lens).
    • Avoid generic glue like "Para 1: introduce the chapter" without naming what is being compared.
  • bridge_terms
    (5–12 tokens; union of H3 bridge terms)
JSONL格式（每个包含H3子小节的H2章节对应一个对象）。
必填字段：
  • section_id
    、
    section_title
  • subsections
    （按大纲顺序排列的
    {sub_id,title}
    列表）
  • synthesis_mode
    （可选值：
    clusters
    、
    timeline
    、
    tradeoff_matrix
    、
    case_study
    、
    tension_resolution
    ）
  • synthesis_preview
    （1-2条项目符号；说明章节将如何整合各H3内容，避免使用“综上所述…”这类模板化表述）
  • throughline
    （3-6条项目符号）
  • key_contrasts
    （2-6条项目符号；若有，可从各H3的
    contrast_hook
    中提取）
  • lead_paragraph_plan
    （2-3条项目符号；仅为规划，非正式文稿）
    • 每条项目符号需针对章节定制，并提及具体的核心要素（对比维度/对比切入点/评估视角）。
    • 避免使用“第一段：介绍章节”这类通用套话，需明确说明要对比的内容。
  • bridge_terms
    （5-12个术语；各H3桥梁术语的合集）

How C5 uses this (chapter lead contract)

C5如何使用此文档（章节引言约定）

The writer uses 
outline/chapter_briefs.jsonl
to draft 
sections/S<sec_id>_lead.md
(body-only; no headings).
Contract (paper-like, no new facts):
  • Preview the chapter’s comparison axes (2–3) and how the H3s connect; do not restate the table of contents.
  • Reuse 
    key_contrasts
    / 
    bridge_terms
    as handles (not templates) so the chapter reads coherent without repeating "Taken together" everywhere.
  • Keep it grounded (>=2 citations later in C5; do not invent new papers here).
作者使用
outline/chapter_briefs.jsonl
来撰写
sections/S<sec_id>_lead.md
（仅正文内容；无标题）。
约定（符合论文风格，无新增事实）：
  • 预览章节的2-3个对比维度，以及各H3子小节如何关联；不得重复目录内容。
  • 将
    key_contrasts
    /
    bridge_terms
    作为核心要素（而非模板）使用，确保章节内容连贯，避免处处重复“综上所述”。
  • 内容需有依据（后续C5中至少引用2篇文献；不得在此处虚构新论文）。

Workflow

工作流程

  1. (Optional) Read 
    GOAL.md
    to pin scope/audience, and inject that constraint into the chapter throughline.
  2. Read 
    outline/outline.yml
    and list H2 chapters that have H3 subsections.
  3. Read 
    outline/subsection_briefs.jsonl
    and group briefs by 
    section_id
    .
  4. For each chapter, produce:
    • a throughline: what the whole chapter is trying to compare/explain
    • key contrasts: 2–6 contrasts that span multiple H3s
    • a synthesis_mode: enforce synthesis diversity across chapters (avoid repeating the same closing paragraph shape)
    • a lead paragraph plan: 2–3 paragraph objectives (what the chapter lead must do)
    • a bridge_terms set to keep terminology stable across H3s
  5. Write 
    outline/chapter_briefs.jsonl
    .
  1. （可选）阅读
    GOAL.md
    以明确范围/受众，并将该约束融入章节的贯穿主线。
  2. 读取
    outline/outline.yml
    ，列出包含H3子小节的H2章节。
  3. 读取
    outline/subsection_briefs.jsonl
    ，按
    section_id
    分组整理简报。
  4. 为每个章节生成以下内容：
    • 贯穿主线：整章要对比/解释的核心内容
    • 核心对比点：2-6个跨多个H3小节的对比点
    • 合成模式：确保各章节的合成方式多样化（避免重复相同的结尾段落结构）
    • 引言段落规划：2-3个段落目标（章节引言必须完成的任务）
    • 桥梁术语集合：保持各H3小节的术语一致性
  5. 写入
    outline/chapter_briefs.jsonl
    文件。

Quality checklist

质量检查清单

  • One record per H2-with-H3 chapter.
  • No placeholders (
    TODO
    /
    …
    /
    (placeholder)
    /template instructions).
  • throughline
    and 
    key_contrasts
    are chapter-specific (not copy/paste generic).
  • lead_paragraph_plan
    bullets explicitly preview 2–3 comparison axes and how the H3 subsections partition them (no generic chapter-intro boilerplate).
  • 每个包含H3的H2章节对应一条记录。
  • 无占位符内容（
    TODO
    /
    …
    /
    (placeholder)
    /模板说明）。
  • throughline
    和
    key_contrasts
    是针对章节定制的内容（非通用复制粘贴内容）。
  • lead_paragraph_plan
    的项目符号明确预览2-3个对比维度，以及H3子小节如何划分这些维度（无通用的章节介绍套话）。

Script

脚本工具

Quick Start

快速开始

  • python .codex/skills/chapter-briefs/scripts/run.py --help
  • python .codex/skills/chapter-briefs/scripts/run.py --workspace workspaces/<ws>
  • python .codex/skills/chapter-briefs/scripts/run.py --help
  • python .codex/skills/chapter-briefs/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 <分号分隔的路径>
  • --outputs <分号分隔的路径>
  • --checkpoint <C#>

Examples

使用示例

  • Default IO: 
    • python .codex/skills/chapter-briefs/scripts/run.py --workspace workspaces/<ws>
  • Explicit IO: 
    • python .codex/skills/chapter-briefs/scripts/run.py --workspace workspaces/<ws> --inputs "outline/outline.yml;outline/subsection_briefs.jsonl;GOAL.md" --outputs "outline/chapter_briefs.jsonl"
  • 默认输入输出： 
    • python .codex/skills/chapter-briefs/scripts/run.py --workspace workspaces/<ws>
  • 显式指定输入输出： 
    • python .codex/skills/chapter-briefs/scripts/run.py --workspace workspaces/<ws> --inputs "outline/outline.yml;outline/subsection_briefs.jsonl;GOAL.md" --outputs "outline/chapter_briefs.jsonl"

Refinement marker (recommended; prevents churn)

优化标记（推荐使用；避免反复修改）

When you are satisfied with chapter briefs, create:
  • outline/chapter_briefs.refined.ok
This is an explicit "I reviewed/refined this" signal:
  • prevents scripts from regenerating and undoing your work
  • (in strict runs) can be used as a completion signal to avoid silently accepting a bootstrap scaffold
当你对章节写作简报满意时，创建以下文件：
  • outline/chapter_briefs.refined.ok
这是一个明确的“已审核/优化”信号：
  • 防止脚本重新生成内容，覆盖你的工作成果
  • （在严格运行模式下）可作为完成信号，避免自动接受初始生成的脚手架内容

Notes

注意事项

  • This helper is a bootstrap; refine manually if needed.
  • 此工具仅为初始生成工具；如有需要，可手动优化内容。