Chapter Briefs (H2 writing cards) [NO PROSE]

• 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

• 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

)

• 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)

outline/chapter_briefs.jsonl

sections/S<sec_id>_lead.md

• 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

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

   .

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 .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#>

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"

Refinement marker (recommended; prevents churn)

• outline/chapter_briefs.refined.ok

• 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.