chapter-briefs
installsforks
How to install chapter-briefs?
willoscar/research-units-pipeline-skills/chapter-briefs
$npx -y skills add WILLOSCAR/research-units-pipeline-skills --skill chapter-briefsBuild 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
SKILL.md
| 1 | # Chapter Briefs (H2 writing cards) [NO PROSE] |
| 2 | |
| 3 | Purpose: turn each **H2 chapter that contains H3 subsections** into a chapter-level writing card so the writer can: |
| 4 | - add a chapter lead paragraph block (coherence) |
| 5 | - keep a consistent comparison axis across the chapter |
| 6 | - avoid “8 small islands” where every H3 restarts from scratch |
| 7 | |
| 8 | This artifact is **internal intent**, not reader-facing prose. |
| 9 | |
| 10 | Why this matters for writing quality: |
| 11 | - Chapter briefs prevent the "paragraph island" failure mode: without a throughline, each H3 restarts and repeats openers. |
| 12 | - Treat `throughline` and `lead_paragraph_plan` as decision constraints, not copyable sentences. |
| 13 | |
| 14 | ## Inputs |
| 15 | |
| 16 | - `outline/outline.yml` |
| 17 | - `outline/subsection_briefs.jsonl` |
| 18 | - Optional: `GOAL.md` |
| 19 | |
| 20 | ## Outputs |
| 21 | |
| 22 | - `outline/chapter_briefs.jsonl` |
| 23 | |
| 24 | ## Output format (`outline/chapter_briefs.jsonl`) |
| 25 | |
| 26 | JSONL (one object per H2 chapter that has H3 subsections). |
| 27 | |
| 28 | Required fields: |
| 29 | - `section_id`, `section_title` |
| 30 | - `subsections` (list of `{sub_id,title}` in outline order) |
| 31 | - `synthesis_mode` (one of: `clusters`, `timeline`, `tradeoff_matrix`, `case_study`, `tension_resolution`) |
| 32 | - `synthesis_preview` (1–2 bullets; how the chapter will synthesize across H3 without template-y “Taken together…”) |
| 33 | - `throughline` (3–6 bullets) |
| 34 | - `key_contrasts` (2–6 bullets; pull from each H3 `contrast_hook` when available) |
| 35 | - `lead_paragraph_plan` (2–3 bullets; plan only, not prose) |
| 36 | - Each bullet should be chapter-specific and mention concrete handles (axes / contrast hooks / evaluation lens). |
| 37 | - Avoid generic glue like "Para 1: introduce the chapter" without naming what is being compared. |
| 38 | - `bridge_terms` (5–12 tokens; union of H3 bridge terms) |
| 39 | |
| 40 | ## How C5 uses this (chapter lead contract) |
| 41 | |
| 42 | The writer uses `outline/chapter_briefs.jsonl` to draft `sections/S<sec_id>_lead.md` (body-only; no headings). |
| 43 | |
| 44 | Contract (paper-like, no new facts): |
| 45 | - Preview the chapter’s comparison axes (2–3) and how the H3s connect; do not restate the table of contents. |
| 46 | - Reuse `key_contrasts` / `bridge_terms` as *handles* (not templates) so the chapter reads coherent without repeating "Taken together" everywhere. |
| 47 | - Keep it grounded (>=2 citations later in C5; do not invent new papers here). |
| 48 | |
| 49 | ## Workflow |
| 50 | |
| 51 | 0. (Optional) Read `GOAL.md` to pin scope/audience, and inject that constraint into the chapter throughline. |
| 52 | 1. Read `outline/outline.yml` and list H2 chapters that have H3 subsections. |
| 53 | 2. Read `outline/subsection_briefs.jsonl` and group briefs by `section_id`. |
| 54 | 3. For each chapter, produce: |
| 55 | - a **throughline**: what the whole chapter is trying to compare/explain |
| 56 | - **key contrasts**: 2–6 contrasts that span multiple H3s |
| 57 | - a **synthesis_mode**: enforce synthesis diversity across chapters (avoid repeating the same closing paragraph shape) |
| 58 | - a **lead paragraph plan**: 2–3 paragraph objectives (what the chapter lead must do) |
| 59 | - a **bridge_terms** set to keep terminology stable across H3s |
| 60 | 4. Write `outline/chapter_briefs.jsonl`. |
| 61 | |
| 62 | ## Quality checklist |
| 63 | |
| 64 | - [ ] One record per H2-with-H3 chapter. |
| 65 | - [ ] No placeholders (`TODO`/`…`/`(placeholder)`/template instructions). |
| 66 | - [ ] `throughline` and `key_contrasts` are chapter-specific (not copy/paste generic). |
| 67 | - [ ] `lead_paragraph_plan` bullets explicitly preview 2–3 comparison axes and how the H3 subsections partition them (no generic chapter-intro boilerplate). |
| 68 | |
| 69 | ## Script |
| 70 | |
| 71 | ### Quick Start |
| 72 | |
| 73 | - `uv run python .codex/skills/chapter-briefs/scripts/run.py --help` |
| 74 | - `uv run python .codex/skills/chapter-briefs/scripts/run.py --workspace <workspace>` |
| 75 | |
| 76 | ### All Options |
| 77 | |
| 78 | - `--workspace <dir>` |
| 79 | - `--unit-id <U###>` |
| 80 | - `--inputs <semicolon-separated>` |
| 81 | - `--outputs <semicolon-separated>` |
| 82 | - `--checkpoint <C#>` |
| 83 | |
| 84 | ### Examples |
| 85 | |
| 86 | - Default IO: |
| 87 | - `uv run python .codex/skills/chapter-briefs/scripts/run.py --workspace <workspace>` |
| 88 | - Explicit IO: |
| 89 | - `uv run python .codex/skills/chapter-briefs/scripts/run.py --workspace <workspace> --inputs "outline/outline.yml;outline/subsection_briefs.jsonl;GOAL.md" --outputs "outline/chapter_briefs.jsonl"` |
| 90 | |
| 91 | ### Refinement marker (recommended; prevents churn) |
| 92 | |
| 93 | When you are satisfied with chapter briefs, create: |
| 94 | - `outline/chapter_briefs.refined.ok` |
| 95 | |
| 96 | This is an explicit "I reviewed/refined this" signal: |
| 97 | - prevents scripts from regenerating and undoing your work |
| 98 | - (in strict runs) can be used as a completion signal to avoid silently accepting a bootstrap scaffold |
| 99 | |
| 100 | ### Notes |
| 101 | |
| 102 | - This helper is a bootstrap; refine manually if needed. |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
