Chapter Lead Writer

Write H2 chapter lead blocks (`sections/S<sec_id>_lead.md`) that preview the chapter's comparison lens and connect its H3 subsections, without adding new fac...

Security Scan

The skill's files, inputs, and runtime instructions align with its stated purpose (generating chapter H2 lead blocks); it requires only a local Python runtime and local outline/citation files and does not request unrelated credentials or network access.

Purpose & Capability

Name/description, required inputs (outline files, chapter briefs, citations), and the included Python scripts/tooling are consistent with a document-generation writer skill. The only declared runtime dependency is python/python3, which is appropriate for bundled .py scripts. There are no unrelated environment variables, credentials, or config paths requested.

Instruction Scope

SKILL.md explicitly instructs the agent to read the listed repository reference files and to execute scripts/run.py in compatibility mode to produce lead files; it also specifies citation scoping rules and 'Network: none'. This is coherent for the skill's purpose. Caveat: runtime behavior depends on executing the bundled Python script/tooling, which can perform arbitrary filesystem and process actions. The SKILL.md lists the intended inputs/outputs, but you should review scripts/run.py/tooling before running to confirm there are no unexpected file reads/writes or network calls.

Install Mechanism

No install spec is provided (instruction-only install), so nothing is downloaded or installed automatically. The package includes Python scripts and modules that are executed directly; that is proportionate and expected for this kind of skill.

Credentials

The skill requests no environment variables or credentials and only requires a Python binary. This is proportionate for a local document-generation utility that operates on workspace files and local citation assets.

Persistence & Privilege

Skill is not forced-always-on (always: false) and uses the normal autonomous-invocation default. It does not declare modifications to other skills or system-wide settings. It will write output files into the workspace (sections/S<sec_id>_lead.md) as intended.

Assessment

This package appears coherent with its stated purpose, but it executes bundled Python code, so: 1) Inspect scripts/run.py and the tooling/*.py files before running to confirm there are no unexpected network calls, telemetry, or access to unrelated system paths. 2) Run the skill in an isolated or disposable workspace (not on a machine holding secrets) so you can review all files it writes (expected outputs are sections/S<sec_id>_lead.md and logs/reports). 3) Ensure the required inputs (outline/outline.yml, outline/chapter_briefs.jsonl, citations/ref.bib) exist and that citation keys are correct. 4) If you do not want code execution, you can use the references and assets in the repo as a prompt-only guide and draft leads without running scripts. If you want extra assurance, share scripts/run.py for a targeted review of network and file I/O behavior.

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.