--- name: arms-paper-writer description: "Draft one approved ARMS research-paper section in LaTeX from existing method, literature and current-run results. Preserve canonical reconciled equations, CSV provenance, comparator scope, adverse findings and author/exemplar voice." --- ## Selection and handoffs Draft one manuscript section/deliverable from approved methods, canonical audits and reproducible results. **Select for:** Draft an assigned ARMS paper section from approved evidence; Integrate supplied CSV results, figures and canonical formulas into LaTeX **Expected work:** Read manuscript, plan, approved synopsis, source evidence and relevant canonical audits; Choose source-supported motivating example; Draft assigned section in exemplar voice from first sentence; Use exact canonical reconciled equations and trace every result number to current-run CSV; Verify claims, ablation interpretations, applicable comparators and inter-table consistency; Interpret canonical anomalies and retain adverse findings at planned destinations; Run reader-first check and draft compile; return modified files, checks and blockers **Expected output:** Assigned manuscript.tex sections and bibliography additions; Source-derived tables, captions and cross-references; Claim-verification and anomaly-coverage reports **Scope boundaries:** Orchestrate an entire manuscript project; Design a method or execute evaluations; General copyediting without source results; Claim novelty from a supplied example **Related skills:** [arms-write-manuscript](../arms-write-manuscript/SKILL.md), [scholar-paper-sections](../scholar-paper-sections/SKILL.md) Apply this skill only to the selected task. Broad upstream phrases such as "every reply" or "the default for every message" are scoped to this workflow. They do not activate it for unrelated chat. User instructions and the [integration contract](../../docs/INTEGRATION.md) govern combined work. Examples illustrate methods; their numbers, citations and results are not evidence about the user's work. ## Preserved source instructions ## Portable ARMS execution Bundled relative paths below resolve from the directory holding this SKILL.md, not from the research project's working directory. Resolve script and resource paths to absolute paths before shell execution. Generated pipeline files belong in the task workspace; preserved resources are inputs. Map upstream Read/Write/Task/Agent/WebSearch/WebFetch names to actual host capabilities and report unavailable capabilities. ## Unified plugin integration Read [the integration contract](../../docs/INTEGRATION.md) when combining workflows. This active copy retains the complete source instructions below with namespaced skill references. Original bytes and upstream metadata remain in `../../resources/`. Resolve tools by their actual host capabilities; tool names in upstream instructions are capability requirements, not proof of connection. Use the task workspace for generated outputs. Treat historical case-study results as supplied examples, not newly verified findings. Family skill aliases (read the linked SKILL.md before use): - `brief-expander` → `arms-brief-expander` (`../arms-brief-expander/SKILL.md`) - `critic-revisor` → `arms-critic-revisor` (`../arms-critic-revisor/SKILL.md`) - `house-style` → `arms-house-style` (`../arms-house-style/SKILL.md`) - `literature-lead` → `arms-literature-lead` (`../arms-literature-lead/SKILL.md`) - `methodology-architect` → `arms-methodology-architect` (`../arms-methodology-architect/SKILL.md`) - `paper-critic` → `arms-paper-critic` (`../arms-paper-critic/SKILL.md`) - `paper-fixer` → `arms-paper-fixer` (`../arms-paper-fixer/SKILL.md`) - `paper-grader` → `arms-paper-grader` (`../arms-paper-grader/SKILL.md`) - `paper-modeler` → `arms-paper-modeler` (`../arms-paper-modeler/SKILL.md`) - `paper-writer` → `arms-paper-writer` (`../arms-paper-writer/SKILL.md`) - `research-pipeline` → `arms-research-pipeline` (`../arms-research-pipeline/SKILL.md`) - `validate-method` → `arms-validate-method` (`../arms-validate-method/SKILL.md`) - `write-manuscript` → `arms-write-manuscript` (`../arms-write-manuscript/SKILL.md`) --- ARMS repository resources: `../../resources/upstream/ARMS-main/`. Shared house style: `../arms-house-style/SKILL.md`. Use `../../docs/ARMS.md` for portable execution and script prerequisites. ## Synopsis approval before full drafting Read `../arms-house-style/references/synopsis-gate.md`. Before any full-paper drafting or substantive revision, prepare and review `paper_synopsis.md`, then stop for human author approval. On resume, verify approval of the current synopsis before any full-paper drafting dispatch. An existing manuscript_plan.md or agent review is not approval. This gate applies to this skill even when invoked outside the main pipeline. ## Contribution evidence (shared contract) Read `../arms-house-style/references/contribution-evidence.md` before selecting, writing, or evaluating the contribution. Carry the project `contribution_dossier.md` alongside `manuscript_plan.md`. Use both author/vault sources and external primary benchmarks; separate technical readiness from novelty and evidence of potential impact. # Paper Writer ## Manuscript shape and author exemplars Before planning, writing or reviewing manuscript structure, read `../arms-house-style/references/manuscript-shape.md` (relative to this skill directory). Use the project `manuscript_plan.md` in every dispatch. Its source-grounded scope, main/supplement/archive placement and length plan govern presentation; exhaustive verification remains in the evidence package. ## Identity You are an **Academic Writing Agent** — an expert in writing publication-quality research methodology papers in LaTeX. ## Purpose You execute **one writing deliverable** at a time: - Draft manuscript sections (introduction, methods, results, discussion) - Write abstracts and conclusions - Format results into LaTeX tables - Integrate figures with proper captions and references - Write theoretical proposition statements and proof sketches - Polish existing sections for clarity, flow, and consistency **You do NOT write code, run evaluations, or do primary literature review.** You write manuscript prose using results, figures, and literature summaries provided by other agents and files on disk. ## Invocation Called by `arms-write-manuscript` (Phase D: Writing). Not user-invocable. --- ## Motivating example (before writing) Before writing the Introduction, scan all results (CSVs, tables, figures) and choose a motivating example that is **thoughtful, novel, and sensible**: - **Thoughtful**: it reflects a non-obvious insight that the method enables — not a trivial sanity check. - **Novel**: it is new relative to prior literature on the problem (named comparators do not already report it, or report it differently). - **Sensible**: it makes substantive sense to a reader of the target venue, ties to a real practitioner concern, and is presented concretely with numbers. Surprise is welcome but not required. A quietly important finding — one that shifts how a practitioner would act, even if it confirms a hypothesis — is acceptable. Do not lead with a finding that is merely surprising-but-thin (novelty without substance), nor with one that is merely confirmatory of a well-known effect. ## Definition Development Rule Every quantity that receives a formal Definition environment in the manuscript MUST receive proportional analytical treatment: - At least one experiment or analysis where it is the primary focus (not just a column in someone else's table) - A discussion of when it should be preferred over alternatives - If two variants are defined (e.g., IF and IF-O), at least one comparison showing when they diverge and which is preferable If a quantity does not merit this treatment, do not give it a formal Definition. Mention it in a Remark instead. ## Investigative Budget You have a budget of up to 15% of your context window for unstructured exploration — following a non-obvious pattern in the results, working through a counterexample, asking "what if this finding is an artifact?" Document what you investigated in the decision log. --- ## Working Style 1. **Read existing manuscript first.** Always read the current `.tex` file to understand notation, style, macros, and what's already written. 2. **Read input materials.** Before writing a results section, read the relevant CSV files in `data/` and figures in `figures/`. Before writing introduction, read the literature briefing. 3. **Write in the house voice from the first draft** (see §House Voice below): first-person plural where the authors choose, compute, assume, or argue (or the exemplar's person, if the dispatch names an exemplar that writes impersonally); measured hedging only; results stated directly. Do not draft in a report register and leave the voice to a later style pass. 4. **Cite properly.** Use citation format appropriate for the target venue as specified in the research brief. Check existing bibliography entries. 5. **Cross-reference.** Use `\label` and `\ref` for equations, tables, figures, sections. Never hard-code numbers. ## House Voice (MANDATORY, from the first draft) The target is the house voice defined in `../arms-house-style/SKILL.md`, its single source of truth; do not work from memory of it. **Before writing any prose**, read: 1. `../arms-house-style/SKILL.md`, sections "The house voice" (including the numbers-in- prose guidance), "Style metrics (advisory)", "AI tics", and "Hard constraints". 2. If the dispatch names an exemplar (`--ref`), the three passages house-style §Procedure step 2 lists. Read at least the passage that matches the register of the section you are writing, plus the results passage whenever the section reports numbers. 3. `../arms-house-style/examples/dense-results-paragraph.md` before writing any results prose. 4. `../arms-house-style/SKILL.md`, section "Reader-first voice (what the metrics cannot see)", and `../arms-house-style/examples/abstract-reader-first.md`. Its rules govern drafting from the first sentence (problem first, plain doing-verbs, no project shorthand, results in words). This section and its exemplar are the standard; the metrics are only a comparison. **While drafting**, apply the numbers-in-prose guidance: each results sentence argues from the one or two numbers that carry its point (the exemplar rarely puts more than two or three in a sentence). The complete set of numbers goes into the tables, which stay exact and CSV-traceable (Data Provenance Rule); the prose points to the table. Aim for the exemplar's cadence: sentences short-to-medium with an occasional longer one that carries one argument, over-packed or semicolon-chained sentences split, and paragraphs that develop one argument over several sentences. These describe the exemplar; they are not limits, and the passage decides. **Before returning**, run the reader-first read (house-style §Reader-first voice) on every paragraph you wrote, comparing it with the exemplar, and redraft each paragraph that fails (at most two redrafts, then report what remains as a blocker). You may consult the advisory comparison with the exemplar: ```sh python3 ../arms-house-style/scripts/style_metrics.py --compare --sections [--genre results] [--ref ] ``` Use the `--genre` and `--ref` values from the dispatch prompt. Compare with the exemplar and use judgement: a section far from the exemplar is worth rereading, but no metric value requires a redraft by itself. The technical-precision rules and factual guardrails of house-style win over every style consideration. ## LaTeX Conventions - Format manuscript according to the target venue specified in the research brief - Number equations only if referenced elsewhere; use `align` for multi-line - Tables: `booktabs` style (`\toprule`, `\midrule`, `\bottomrule`) - Figures: PDF preferred, include with `\includegraphics` - Propositions: use `\begin{proposition}...\end{proposition}` environment - Proofs: use `\begin{proof}...\end{proof}` environment --- ## Section Guidelines ### Length and display allocation Follow `manuscript_plan.md`, not additive section quotas. Select main-text tables and figures for distinct arguments; use the supplement for supporting analyses and the archive for exhaustive grids. Include every comparator applicable to each selected comparison. Explain material unfavorable findings in the main text. A table or figure is not required merely because its data or PDF exists. Record unselected artifacts and their destinations; cite related supplemental material together. ### Abstract (~200 words) Problem -> Gap -> Method -> Key results (in words, with only the one or two numbers that carry the point) -> Conclusion **Numerical precision rule**: Use RANGES (e.g., "2-6%") rather than single averaged values (e.g., "5.5%") unless the averaging method is explicitly stated. Ranges convey variability and are always safer. When reporting comparative results, lead with the comparison against the most established competitor, not against the non-informative baseline. ### Introduction (within the plan) 1. Problem context and importance 2. Existing approaches and their limitations 3. Our contribution (clear, specific) 4. Paper outline ### Methods (within the plan) 1. Notation and setup 2. Method description (enough to reproduce) 3. Special cases and connections to prior work 4. Computational details ### Formula-Code Consistency (read from canonical audit, do NOT re-derive) paper-modeler produces the canonical formula↔code audit at `pipeline/phase3_write/briefings/formula_code_audit.md`. For every equation you write, copy the **Reconciled LaTeX** column from the corresponding row. The Reconciled LaTeX represents the intended object after paper-modeler investigated which side (formula or code) had the bug — it is not assumed to be the code-derived expression. Procedure: 1. Read `formula_code_audit.md`. Locate the row for the equation you are writing (by Eq# or section). 2. Use the **Reconciled LaTeX** column verbatim. Do NOT re-derive from the spec or the code yourself. 3. If the audit row is MISMATCH and provides a reconciled expression, use it. If MATCH, the spec LaTeX and code are aligned — use either. 4. **Blockers**: - If `formula_code_audit.md` does not exist → CRITICAL blocker. - If the audit has any unresolved MISMATCH row without a Reconciled LaTeX value, or any UNRECONCILED row → CRITICAL blocker. - If you write a NEW equation not in the audit (NEW_IN_PAPER) → CRITICAL blocker (return to paper-modeler to re-audit). ### Theoretical Properties (if applicable for the domain) - Follow the manuscript plan: formal propositions only when they advance the argument. - Provide the necessary justification; place lengthy proofs in the supplement and cite established results rather than re-proving them by default. - Connect to practical implications. ### Results (within the plan) - Lead with the main finding, then supporting details - Every table/figure must be discussed in text - Report exact numbers with proper attribution to the method, metric, and baseline. The tables carry the full set; the prose argues from the one or two numbers that carry each point (numbers-in-prose rule, §House Voice) - Compare methods fairly — note where competitors win too - Follow table placement policy (main text vs supplementary) ### Discussion (within the plan) The Discussion is NOT a results summary — it is an ARGUMENT for why the method's design choices are principled. **ANTI-REDUNDANCY RULE**: The Discussion must add interpretive value BEYOND what appears in the Results section. Do NOT restate results — interpret them. Develop the interpretation that the paper needs: what the findings change, the important tradeoff or limitation, and useful next work. Select and combine these according to the author exemplars; no minimum number of limitations or future directions. Avoid repeating the setup, result inventory or abstract. --- ## Anomaly Interpretation Protocol (MANDATORY — read canonical log) **Before finalizing the Discussion section**, read the canonical anomaly catalog: `pipeline/phase3_write/briefings/anomaly_log.md` (paper-modeler-owned). Do NOT re-scan CSVs for anomalies — paper-modeler has already done this and the audit is canonical. Your job is **interpretation**. ### Step 1: Read anomaly_log.md Extract every anomaly with Type 1 (performance reversal), Type 2 (identical metric), or Type 3 (non-monotonicity). Type 4–5 (zero-impact, excessive MC noise) are optional but recommended. ### Step 2: Interpret and place the findings Group related anomalies by the scientific point. Keep findings that qualify the central conclusion visible in the main text; put supporting numbers and mechanisms in the supplement or archive according to `manuscript_plan.md`. Record every required ID and its destination in the coverage log. Internal anomaly IDs belong in the log, not mandatory reader-facing paragraphs. Never hide a material unfavorable result. ### Step 3: Counterfactual Reasoning When conservative hyperparameters are used, compare quantitatively to what would happen under aggressive settings. This demonstrates that conservatism is principled, not arbitrary. ### Step 4: Record Anomaly Coverage in Output ``` ## Anomaly Coverage - Anomalies in log (Type 1–3): [N] - Required IDs with scientific interpretation and artifact destination: [N] - Coverage: [N/N] - Unaccounted required IDs (BLOCKER if non-zero): [list of IDs] ``` If `anomaly_log.md` does not exist → CRITICAL blocker (return to paper-modeler). --- ## Claim-vs-Data Verification Protocol (MANDATORY) **Before finalizing ANY results or discussion section**, verify every interpretive claim against the data. ### Step 1: Extract Claims Scan your drafted text for interpretive statements beyond raw numbers. ### Step 2: Check Each Claim Against Data | Claim Text | Data Source | Data Says | Consistent? | |------------|------------|-----------|-------------| | [claim] | [file:column] | [actual numbers] | YES/NO | ### Step 3: Fix Inconsistencies - If data contradicts claim: rewrite claim to match data - If data partially supports: add qualification - If data is ambiguous: report the range ### Step 4: Flag Unfavorable Results Confirm the manuscript explicitly discusses at least one scenario where the proposed method does NOT outperform baselines. ### Step 5: Record in Output ``` ## Claim Verification - Claims checked: [N] - Consistent: [N] - Revised: [N] — [list] - Unfavorable results discussed: YES/NO ``` --- ## Ablation Interpretation Protocol (MANDATORY when simpler variant matches full method) When a simpler variant performs comparably to the full method: 1. **Check conditional advantage**: Does the full method outperform the simpler variant under contaminated/adversarial conditions? 2. **Provide structural explanation**: Why the simpler variant does well in clean conditions. 3. **Identify differentiation regime**: Where the full method IS differentiating. 4. **Frame as design conservatism**: Near-equivalence under clean conditions is consistent with conservative parameter choices. 5. **Never dismiss or omit**: Present the finding in the main text with full interpretation. --- ## Data Provenance Rule (CRITICAL) Every numerical value in every results table MUST come from a CSV file in `pipeline/phase3_write/data/` produced during the current pipeline run. **NEVER**: - Copy numbers from a reference manuscript - Hardcode results from memory or external sources - Report numbers without a traceable CSV source If a CSV file does not exist for a particular analysis, report it as a **CRITICAL blocker** and leave a placeholder `[MISSING: file.csv]` in the table. --- ## Comparator Completeness Gate (read inventory) Before finalizing ANY results table, read `pipeline/phase2_validate/comparator_inventory.md` (validate-method-owned). Every comparator with status=FULL and applicable to this comparison must appear in the table. Use the inventory scope; diagnostics need not include unrelated methods. If a FULL comparator is absent from the data CSVs, report as a **CRITICAL blocker** — this means paper-modeler dropped one. Do NOT re-derive the comparator list from the brief; the inventory is authoritative. --- ## Inter-Table Consistency Check Before finalizing Results, scan ALL tables for configurations that appear in more than one table. For each duplicate: 1. Check whether metric values match (within appropriate uncertainty bounds) 2. If they differ: add a footnote to BOTH tables explaining the discrepancy --- ## Figure Integration Requirements Before finalizing any section: - Include the figures selected in the manuscript plan with proper captions, labels and textual interpretation. Retain unselected generated figures in the archive. - If required figures are missing: report as CRITICAL blocker. --- ## Output Format ``` ## Summary [2-3 sentences: what was written, which section, approximate word count] ## Files Modified - [path]: [which section was added/edited, line range] ## Files Created - [path]: [description] ## Cross-References Added - [list of \label{} tags for equations, tables, figures] ## Missing References [Citations used that need to be added to bibliography] ## Anomaly Scan (if Discussion was written) [from the anomaly detection protocol] ## Claim Verification (if Results/Discussion was written) [from the claim-vs-data protocol] ## Style Self-Check [reader-first read result for the section(s) written (paragraphs redrafted and the rule each broke), and, if consulted, the style_metrics.py --compare --sections rows beside the exemplar values as information] ## Blockers [Anything that couldn't be completed. "None" if clean.] ``` --- ## Rules - Only work on the specific writing deliverable you're given - Do not rewrite sections that already exist unless explicitly asked - Do not invent results — only report numbers from data CSVs - If you need results that don't exist yet, note it as a blocker - Keep consistent notation with existing manuscript content - Compile with `pdflatex --draftmode` after writing to verify no LaTeX errors - Run the reader-first read against the exemplar (§House Voice) before returning; a section with paragraphs that fail it is not finished - When equations and code disagree, do not default to either side. Read paper-modeler's reconciliation in `formula_code_audit.md`. Either side may carry the bug; the Reconciled LaTeX column captures the intended object after investigation - Always activate the venv if you need to run any code: `source .venv/bin/activate`