subsection-polisher_skill

Overview

This skill polishes a single H3 subsection file under sections/ so it reads like survey-grade prose before merging into the draft. It rewrites the opener into a tension → why-it-matters → thesis structure, adds explicit contrasts and an evaluation anchor, and inserts a subsection-specific limitation without changing any citation keys. The tool is intentionally local: operate one subsection at a time and stop if evidence is insufficient.

How this skill works

The skill loads the subsection’s writer context or fallback evidence packs, extracts a tension, contrast cards, an evaluation anchor, and a limitation hook, then performs a sequence of targeted rewrites. It enforces immutable citation keys and scoped citations, embeds citations into claim sentences, and ensures the H3 contains contrasts, a cross-paper synthesis paragraph (≥2 citations), an evaluation anchor, and a limitation. If required evidence is missing, the skill halts and signals upstream remediation rather than invent facts.

When to use it

• When sections/S*.md exists but reads template-y or like generator output
• Before running section-merger to ensure each H3 is paper-ready
• When you need a single subsection improved without touching other sections
• When you have the evidence pack/writer_context for that subsection available
• Skip if the subsection is missing, evidence is incomplete, or Approve C2 is not recorded

Best practices

• Run the skill on one H3 at a time and rerun quality gates after edits
• Keep citation keys unchanged and confined to the subsection scope
• Do not strengthen claims beyond what the supplied evidence supports
• Stop and route upstream if you cannot produce a concrete contrast or evaluation anchor without guessing
• Embed citations in the sentence that asserts the claim, avoid end-of-paragraph citation dumps
• Add a limitation tied to protocol mismatch or missing details rather than boilerplate caveats

Example use cases

• Turn a bullet-list H3 into a short, argument-driven paragraph set ready for merge
• Add explicit A vs B contrasts and an evaluation anchor to a thin methods comparison H3
• Produce a cross-paper synthesis paragraph using at least two local citations in the same paragraph
• Insert a subsection-specific caveat when protocol details in evidence are incomplete
• Polish subsections incrementally to converge the whole paper without large rewrites