--- name: willoscar/subsection-writer source: https://app.decimal.ai/s/willoscar-subsection-writer@1/SKILL.md source_sha256: 4b6171a30326 --- # 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.md` - `references/paragraph_jobs.md` - `references/paragraph_job_archetypes.md` when adjusting paragraph-role behavior or refactoring writer policy out of Python - `references/bootstrap_assembly.md` when reasoning about compatibility-mode bootstrap behavior Read as needed: - `references/opener_catalog.md` when paragraph 1 sounds generic or narrated - `references/contrast_moves.md` when building A-vs-B comparison paragraphs - `references/eval_anchor_patterns.md` when making performance / robustness / benchmark claims - `references/limitation_moves.md` when adding caveats or local conclusions - `references/examples_good.md` and `references/examples_bad.md` for calibration only Machine-readable contract: - `assets/subsection_writer_context.schema.json` - `assets/bootstrap_paragraph_templates.json` - `assets/paragraph_job_templates.json` ## Inputs Required: - `DECISIONS.md` (must include `Approve C2`) - `outline/outline.yml` - `outline/writer_context_packs.jsonl` (preferred) - `citations/ref.bib` Optional but useful: - `outline/subsection_briefs.jsonl` - `outline/evidence_drafts.jsonl` - `outline/evidence_bindings.jsonl` - `outline/anchor_sheet.jsonl` - `outline/chapter_briefs.jsonl` ## Outputs Keep the current contract: - `sections/S.md` for H3 bodies - `sections/sections_manifest.jsonl`, refreshed across all section files already produced by the three writer Skills - `sections/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 ` ## 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 C2` - `outline/outline.yml` to enumerate chapter / subsection files - `outline/writer_context_packs.jsonl` as the primary drafting input - `citations/ref.bib` for in-scope citations - `outline/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 ` ### All Options - `--workspace ` - `--unit-id ` - `--inputs ` - `--outputs ` - `--checkpoint ` ### Examples - `uv run python .codex/skills/subsection-writer/scripts/run.py --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.