Chapter Briefs

---

name: chapter-briefs description: 'Build per-chapter (H2) writing briefs (NO PROSE) so the final survey reads like a paper (chapter leads + cross-H3 coherence) without inflating the ToC.

Trigger: chapter briefs, H2 briefs, chapter lead plan, section intent, 章节意图, 章节导读, H2 卡片.

Use when: outline/outline.yml + outline/subsection_briefs.jsonl exist and you want thicker chapters (fewer headings, more logic).

Skip if: the outline is still changing heavily (fix outline/mapping first).

Network: none.

Guardrail: NO PROSE; do not invent papers; only reference subsection ids and already-mapped papers.' version: 0.1.0 metadata: openclaw: requires: anyBins: - python3 - python

---

Chapter Briefs (H2 writing cards) [NO PROSE]

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.

Inputs

outline/outline.yml

outline/subsection_briefs.jsonl

Optional: GOAL.md

Outputs

outline/chapter_briefs.jsonl

Output format (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)

How C5 uses this (chapter lead contract)

The writer uses outline/chapter_briefs.jsonl to draft sections/S_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).

Workflow

0. (Optional) Read GOAL.md to pin scope/audience, and inject that constraint into the chapter throughline. 1. Read outline/outline.yml and list H2 chapters that have H3 subsections. 2. Read outline/subsection_briefs.jsonl and group briefs by section_id. 3. 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 4. Write 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).

Script

Quick Start

python scripts/run.py --help

python scripts/run.py --workspace workspaces/

All Options

--workspace

--unit-id

--inputs

--outputs

--checkpoint

Examples

Default IO:

- python scripts/run.py --workspace workspaces/

Explicit IO:

- python scripts/run.py --workspace workspaces/ --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

Notes

This helper is a bootstrap; refine manually if needed.

Default IO:

- python scripts/run.py --workspace workspaces/

Explicit IO:

- python scripts/run.py --workspace workspaces/ --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

Notes

This helper is a bootstrap; refine manually if needed.