| name | subsection-writer |
| description | Write survey prose into per-section files under `sections/` so each unit can be QA'd independently before merging.
**Trigger**: subsection writer, per-section writing, split sections, sections/, 分小节写, 按章节拆分写作.
**Use when**: `Approve C2` is recorded and writer packs exist (`outline/writer_context_packs.jsonl`); you want evidence-bounded drafting without a monolithic one-shot draft.
|
Subsection Writer (compatibility router)
Purpose: write or refine per-section survey prose under sections/ while keeping the current pipeline contract unchanged.
Compatibility mode:
- output paths stay the same
scripts/run.py still handles approval checks, missing-file bootstrap, and sections/sections_manifest.jsonl- writing guidance now lives in
references/ instead of being encoded primarily in the script
Load Order
Always read:
references/overview.mdreferences/paragraph_jobs.mdreferences/paragraph_job_archetypes.md when adjusting paragraph-role behavior or refactoring writer policy out of Pythonreferences/bootstrap_assembly.md when reasoning about compatibility-mode bootstrap behavior
Read as needed:
references/opener_catalog.md when paragraph 1 sounds generic or narratedreferences/contrast_moves.md when building A-vs-B comparison paragraphsreferences/eval_anchor_patterns.md when making performance / robustness / benchmark claimsreferences/limitation_moves.md when adding caveats or local conclusionsreferences/examples_good.md and references/examples_bad.md for calibration only
Machine-readable contract:
assets/subsection_writer_context.schema.jsonassets/bootstrap_paragraph_templates.jsonassets/paragraph_job_templates.json
Inputs
Required:
DECISIONS.md (must include Approve C2)outline/outline.ymloutline/writer_context_packs.jsonl (preferred)citations/ref.bib
Optional but useful:
outline/subsection_briefs.jsonloutline/evidence_drafts.jsonloutline/evidence_bindings.jsonloutline/anchor_sheet.jsonloutline/chapter_briefs.jsonl
Outputs
Keep the current contract:
sections/S<sub_id>.md for H3 bodiessections/sections_manifest.jsonl, refreshed across all section files already
produced by the three writer Skillssections/h3_bodies.refined.ok after a model or human has reviewed the
generated H3 bodies and is submitting U100 for mandatory acceptance
front-matter-writer owns Abstract, Introduction, Related Work, Discussion, and
Conclusion. chapter-lead-writer owns H2 lead blocks. This Skill reads those
files while refreshing the shared manifest but does not claim their authorship.
Writer policy
The active rule is move coverage, not paragraph quota.
A subsection should cover the necessary argument moves the pack supports; do not pad to a fixed count when the evidence does not justify it.
Opener / ending policy:
- generate 2-4 opener candidates from the pack's actual tension, contrast, protocol, or limitation signals; keep the most content-bearing option instead of reusing one stock stem everywhere
- let subsection endings emerge from evidence-bearing comparison / limitation material; do not append a fixed “safest synthesis / decision rule” closer just to make the paragraph feel finished
- normalize internal axis labels into natural reader prose; slash-style brief handles should remain planning metadata, not leak unchanged into the paper
Script boundary
Use scripts/run.py as a helper only:
- it may bootstrap missing H3 files and refresh the manifest
- bootstrap prose is assembled deterministically from writer packs and the
versioned template assets; it is inspectable fallback material, not a claim
of model authorship or final prose quality
- it must not be treated as the canonical source of prose shape or voice policy
- it must not self-certify its bootstrap prose: the script never creates
sections/h3_bodies.refined.ok
- the marker is only U100's submission attestation; it is created before the
downstream
writer-selfloop, so it cannot mean that the self-loop already passed
- mandatory acceptance independently compares H3 sentences with the Run-selected
writer template assets and rejects literal residue above the Pipeline limit
writer-selfloop calls the shared strict section checker, which recomputes the
H3 measure before the report can PASS- the mandatory
pipeline-auditor measures the entire merged draft and writes a
scorecard whose verdict and dimensions the Harness projects into the
evaluation ledger
- the current 10% limit is an initial policy target; a published current-contract
replay measures 0/226 residue for one retained Artifact set, while clean
from-scratch and cross-topic reproduction remain open
- if the marker predates a writer input or the writer script, it is stale and the next run removes it before regenerating bootstrap prose
Quick Start
uv run python .codex/skills/subsection-writer/scripts/run.py --workspace <workspace>
Troubleshooting
- If the pack is thin, stop and route upstream instead of padding prose.
- If the subsection sounds narrated, reload
references/opener_catalog.md and references/examples_bad.md.
- If a claim lacks protocol context, reload
references/eval_anchor_patterns.md before rewriting.
Execution notes
When running in compatibility mode, scripts/run.py currently consumes:
DECISIONS.md for Approve C2outline/outline.yml to enumerate chapter / subsection filesoutline/writer_context_packs.jsonl as the primary drafting inputcitations/ref.bib for in-scope citationsoutline/subsection_briefs.jsonl, outline/evidence_drafts.jsonl, outline/evidence_bindings.jsonl, outline/anchor_sheet.jsonl, and outline/chapter_briefs.jsonl as optional enrichment sources
Script
Quick Start
uv run python .codex/skills/subsection-writer/scripts/run.py --workspace <workspace>
All Options
--workspace <dir>--unit-id <id>--inputs <a;b;...>--outputs <a;b;...>--checkpoint <C*>
Examples
uv run python .codex/skills/subsection-writer/scripts/run.py --workspace <workspace>
Troubleshooting
- If
DECISIONS.md lacks Approve C2, stop and fix approval first.
- If
outline/writer_context_packs.jsonl is thin, reroute upstream instead of padding prose.
- If citation scope looks wrong, re-check
citations/ref.bib and the writer packs before editing output text.
