Chapter Briefs

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. **Tri...

Security Scan

The skill's code, runtime instructions, and requested resources are consistent with its stated purpose (generating chapter-level briefs from outline and subsection briefs); it requires only Python and has no network/credential demands.

Purpose & Capability

Name/description match the actual behavior: the script reads outline/subsection briefs and emits chapter_briefs.jsonl. Requiring python3/python is appropriate and proportional. No unrelated credentials or binaries are requested.

Instruction Scope

SKILL.md and scripts only reference workspace files (outline/outline.yml, outline/subsection_briefs.jsonl, optional GOAL.md) and produce outline/chapter_briefs.jsonl. Instructions do not ask the agent to read unrelated system files, call external endpoints, or exfiltrate secrets. Guardrails (NO PROSE, no invented facts) are explicit.

Install Mechanism

No install spec; this is a bundled script executed locally with Python. All code is included in the repo; there are no downloads or external package installs in the manifest.

Credentials

No environment variables, credentials, or config paths are required. The only declared runtime requirement is Python, which is justified by the shipped scripts.

Persistence & Privilege

always:false and no special privileges requested. The script writes outputs into the provided workspace and uses a local 'chapter_briefs.refined.ok' freeze marker — no system-wide or other-skill configuration is altered.

Assessment

This skill appears coherent and limited in scope: it reads outline/outline.yml and outline/subsection_briefs.jsonl (and optionally GOAL.md) from the workspace and writes outline/chapter_briefs.jsonl. It runs locally in Python and does not make network calls or require credentials. If you will run untrusted code, review the included Python files (scripts/run.py and tooling/*) yourself; otherwise it's reasonable to install/use. Note: the agent can invoke the skill autonomously by default (normal for skills) — if you want to avoid that, restrict agent invocation in your agent settings.

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

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/<ws>

All Options

• --workspace <dir>
• --unit-id <U###>
• --inputs <semicolon-separated>
• --outputs <semicolon-separated>
• --checkpoint <C#>

Examples

• Default IO:
  • python scripts/run.py --workspace workspaces/<ws>
• Explicit IO:
  • python 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

Notes

• This helper is a bootstrap; refine manually if needed.