chapter-lead-writer

# Chapter Lead Writer ## Purpose This skill writes the body-only lead block that sits under an H2 heading and makes a chapter with multiple H3 subsections read like one argument. This `SKILL.md` is now the **package router**, not the full method manual. ## Migration status This package is in **P0 compatibility-preserving migration**: - `references/` and `assets/` now hold the intended knowledge and contract layers. - `scripts/run.py` remains in **compatibility mode** for active generation. - a later script-thinning pass should move more judgment and exemplars out of Python and leave the script with deterministic execution and validation only. For now, preserve the existing output contract and treat `scripts/run.py` as the execution source of truth. ## Inputs Required: - `outline/outline.yml` - `outline/chapter_briefs.jsonl` - `citations/ref.bib` Optional: - `outline/writer_context_packs.jsonl` ## Outputs For each H2 section with H3 subsections: - `sections/S<sec_id>_lead.md` ## Output contract Keep these file-shape rules stable: - each lead file is body-only and contains no headings - each lead file previews the chapter lens and connects multiple H3s as one argument - each lead file stays within the chapter's existing citation scope - each lead file adds no new facts that are not supported later in the chapter ## Load Order Always read: - `references/overview.md` - `references/lead_block_archetypes.md` Read by task: - `references/throughline_patterns.md` — when chapter briefs are thin or hard to convert into a throughline - `references/bridge_examples.md` — when the lead needs stronger H3 transitions without slide narration - `references/bad_narration_examples.md` — when removing table-of-contents narration, planner talk, count-based openers Machine-readable assets: - `assets/lead_block_contract.json` — stable package contract for lead-block shape - `assets/lead_block_compatibility_defaults.json` — fallback phrasing, item limits, joiners, sentence cadence ## Routing rules Use this skill in the following order: 1. Confirm the chapter is eligible - identify H2 sections with H3 subsections from `outline/outline.yml` - locate the corresponding chapter brief in `outline/chapter_briefs.jsonl` 2. Load the method - read `references/overview.md` - read `references/lead_block_archetypes.md` - load the other reference files only if the chapter brief or current prose needs them 3. Check citation scope - if `outline/writer_context_packs.jsonl` exists, use it for cross-cutting chapter citations - keep any citations inside the existing chapter scope and validate keys against `citations/ref.bib` 4. Execute - **current phase**: use `scripts/run.py` in compatibility mode to preserve active behavior and output shape - **future phase**: keep `scripts/run.py` for deterministic execution only, with the writing method and anti-pattern inventory living in `references/` ## Compatibility mode note `scripts/run.py` still contains active lead-generation logic. That is temporary. For now: - do not treat the current script wording as the target architecture - do treat `assets/lead_block_compatibility_defaults.json` as the primary compatibility-mode wording source - do not copy large prose instructions back into `SKILL.md` - do preserve the current output contract while reducing obvious narration stems in the active path ## What this skill should guarantee Regardless of where the detailed method lives, this skill should produce chapter leads that: - state the chapter's comparison lens rather than narrating the outline - connect the H3 subsections as one argument, not as isolated stops on a tour - introduce recurring contrasts without slash-list jargon - keep the evaluation or calibration lens visible at a high level - avoid slide narration, planner talk, and repeated stock openers - choose from multiple candidate lead frames when possible (lens-first / sequence-first / comparison-first) and keep the least narrated option instead of reusing one stock cadence everywhere ## Block conditions Stop and route upstream if any of these are true: - `outline/chapter_briefs.jsonl` is missing - the target H2 section has no H3 subsections - the chapter brief is too incomplete to infer a throughline safely - the requested lead would require new facts or out-of-scope citations ## Script role `scripts/run.py` should currently be treated as a **compatibility executor**. Its long-term role after script thinning is narrower: - chapter discovery - brief loading and normalization - contract validation - deterministic report writing It is not the long-term home for lead archetypes, bridge examples, or narration anti-patterns. ## Script ### Quick Start - `python scripts/run.py --workspace <workspace_dir>` ### All Options - `--workspace <dir>` - `--unit-id <id>` - `--inputs <a;b;...>` - `--outputs <a;b;...>` - `--checkpoint <C*>` ### Examples - `python scripts/run.py --workspace workspaces/<ws>` ## Troubleshooting - If `outline/chapter_briefs.jsonl` is missing or too thin, rebuild chapter briefs first. - If `outline/writer_context_packs.jsonl` is missing, the script will still run but with a thinner citation pool. - If a generated lead sounds narrated, patch the compatibility asset and references before changing Python.