subsection-briefs_skill

Overview

This skill builds per-subsection writing briefs (NO PROSE) that convert each H3 into an executable intent card. Outputs are evidence-first, scoped briefs that drive drafting by checkable comparison axes, clusters, and a paragraph-level plan rather than reusable prose templates. It prevents template leakage and enforces scope and evidence hygiene.

How this skill works

The skill reads outline/outline.yml, outline/mapping.tsv, and papers/paper_notes.jsonl, then scaffolds one JSONL brief per H3 with scope rules, a concrete tension, a one-sentence thesis, 3–5 specialized axes (with why-notes), 2–3 paper clusters, and an 8–10 paragraph plan with connector contracts. It flags missing evidence and uses conservative placeholders (explicit "unknown" slots) so writers only assert claims supported by mapped papers.

When to use it

• You have outline/outline.yml + outline/mapping.tsv + papers/paper_notes.jsonl and want section-by-section drafting without scaffold bleed
• When you need briefs that an author can execute without inventing claims or prose
• Before handing subsections to a human writer or a prose generator to ensure evidence-first output
• When outline/subsection_briefs.jsonl is absent or contains placeholders that must be removed
• When you need consistent scope rules and comparison axes to avoid repeated openers

Best practices

• Keep each tension_statement unique and subsection-specific to avoid repeated framing
• Specialize axes to the subsection title and mapped papers; attach a short "why this comparison matters" note to each axis
• Make scope_rule explicit: include/exclude lists and a policy for cross-scope citations
• Cluster mapped papers into 2–3 themed groups (2–5 papers each) and justify clustering with axis links
• Write paragraph_plan items as intent+connector (no prose) so paragraphs form a coherent argumentative chain
• Run a uniqueness sweep to remove repeated tension stems and copyable connector phrases

Example use cases

• Turn an H3 about "planning with tools" into a brief that compares search depth, action schema complexity, and error attribution
• Create subsection briefs for a literature review so downstream writers cite only mapped paper_ids/bibkeys
• Refine bootstrap script output into evidence-aware briefs when paper notes are title-only or abstract-only
• Gate automated drafting by requiring outline/subsection_briefs.jsonl with no placeholders before generation
• Produce decision-guidance paragraphs for engineering trade-offs (cost/latency/reliability) tied to concrete evidence