Agent-Skills.md

Agent Skills: Subsection Writer (compatibility router)

|

UncategorizedID: willoscar/research-units-pipeline-skills/subsection-writer
37425

Install this agent skill to your local

pnpm dlx add-skill https://github.com/WILLOSCAR/research-units-pipeline-skills/tree/HEAD/.codex/skills/subsection-writer

Skill Files

Browse the full folder contents for subsection-writer.

Download Skill

Loading file tree…

.codex/skills/subsection-writer/SKILL.md

Skill Metadata

Name
subsection-writer
Description
|

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/abstract.md
  • sections/discussion.md
  • sections/conclusion.md
  • sections/S<sec_id>.md for H2-without-H3 bodies
  • sections/S<sec_id>_lead.md for H2 lead blocks
  • sections/S<sub_id>.md for H3 bodies
  • sections/sections_manifest.jsonl

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
  • it must not be treated as the canonical source of prose shape or voice policy

Quick Start

  • python .codex/skills/subsection-writer/scripts/run.py --workspace workspaces/<ws>

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

  • python .codex/skills/subsection-writer/scripts/run.py --workspace <workspace_dir>

All Options

  • --workspace <dir>
  • --unit-id <id>
  • --inputs <a;b;...>
  • --outputs <a;b;...>
  • --checkpoint <C*>

Examples

  • python .codex/skills/subsection-writer/scripts/run.py --workspace workspaces/<ws>

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.