Manuscript Writing

Manuscript Writing

Overview

Guide the writing of a research manuscript with the same discipline Eureka applies to everything else: gates before each section, traceability for every claim, fresh-eyes review after each section, and a hard prohibition on writing about results that don't exist yet.

Core principle: A manuscript is a report of work done, not a plan for work to do. Every section has a prerequisite, every claim has a source, and every figure was generated by a script.

The Iron Law

NO MANUSCRIPT CLAIM WITHOUT A TRACEABLE SOURCE.
NO SECTION WITHOUT ITS PREREQUISITE DATA.

Writing a Results section before results exist is fabrication. Writing a Discussion before Results are finalized is fiction. The prerequisites are not negotiable.

When to Use

Use this skill when:

• The user says "let's write the paper", "draft the methods section", "start the manuscript", "write up the results"
• At least one section's prerequisites are met (typically: design doc exists → Introduction can be written)
• Research-review has passed for the relevant experiment phase

Do NOT use when:

• The user is still designing or running experiments (use the appropriate earlier skill)
• The user wants to write a research journal entry (use eureka:research-journal)
• The user wants to audit an already-written manuscript (use eureka:claims-audit)

Checklist

You MUST create a task for each of these and complete them in order:

1. Determine manuscript structure — ask the user: what sections does this paper have? What format (LaTeX, Markdown)? What target journal?
2. Verify prerequisites per section — check which sections can be written now (see Prerequisites Gate below)
3. Lock the narrative arc (Discovery-Adjusted Framing) — before writing any section, run the checkpoint (Per-Section Workflow Step 3) to confirm or revise the altitude and story arc committed at brainstorming, now that results exist. Fires once per manuscript.
4. Write sections in prerequisite order — start with the earliest-ready section
5. Per section: write → inline self-check → dispatch section-reviewer → fix → approve
6. Write Abstract last — only after all other sections pass review
7. Final pass — read the complete manuscript for cross-section flow and consistency
8. Transition — invoke eureka:claims-audit for the full manuscript audit

Writing Prerequisites Gate

Sections can be written out of order as long as each section's own prerequisite is met. For example, Methods can be written before Results if the hypothesis is registered and the plan exists — you're describing what you did, not what you found.

Writing Discipline Rules

These rules are domain-agnostic. They apply regardless of field, format, or target journal.

1. Every factual claim needs a citation

In LaTeX: \cite{}, \citep{}, \citet{} In Markdown: [@key], (Author, Year)

No "It is well known that...", "Studies have shown...", or "Previous work demonstrates..." without a specific citation. If you can't cite it, you can't claim it.

2. Every quantitative value traces to a source file

If you write r = 0.86 or p < 0.001 or N = 47, there must be a file in results/ (or equivalent) that contains that exact value. This is pre-auditing for eureka:claims-audit — catch traceability failures during writing, not after.

When writing a number, note the source inline as a comment:

• LaTeX: r = 0.86 % source: results/cv_results.json
• Markdown: r = 0.86 <!-- source: results/cv_results.json -->

3. Every figure/table reference points to an existing artifact

In LaTeX: \ref{fig:X} requires a \label{fig:X} in the document AND a real file in figures/ generated by a script. In Markdown: ![Figure 1](figures/fig1.png) requires figures/fig1.png to exist and be script-generated.

No manually drawn figures. No screenshots pasted into the manuscript. Figures must be reproducible.

HARD-RULE — auto-trigger eureka:figure-design: when writing a section that cites a figure that does not yet exist OR an existing figure's design needs revision, you MUST invoke eureka:figure-design before continuing to write prose that depends on the figure. Do NOT write around a missing figure with placeholder prose. figure-design enforces chart-type selection, typography, colorblind-safe palettes, and journal-specific export specs. manuscript-writing writes the text that references the figure; figure-design creates the figure itself.

This rule is stronger than the prior "invoke when needed" phrasing because external feedback showed users skipping figure-design for new figures and producing figures that failed journal spec.

4. Variables defined on first use

Every symbol in an equation must be defined the first time it appears. A reader encountering \alpha for the first time should immediately see "where \alpha is the diffusion rate constant."

5. Abbreviations spelled out on first use

Spell out in the Abstract AND again on first use in the main text. Abstracts and main text are read independently.

6. One idea per paragraph

Structure: topic sentence → evidence → analysis → transition to next paragraph. If a paragraph covers two ideas, split it.

7. Active voice preferred

"We propose..." not "It is proposed that..." "Our model achieves..." not "It was found that the model achieves..."

Passive voice is acceptable when the agent is genuinely irrelevant, but active voice is the default.

8. Abstract written LAST

The Abstract summarizes a finished paper. Writing it first means guessing at results. Write an outline or a 3-sentence summary if you need to organize your thoughts — but the real Abstract is the last thing written.

Per-Section Workflow

For each section, follow these steps in order:

Step 1: Check prerequisite

Verify the prerequisite from the table above. If not met, tell the user which prerequisite is missing and suggest the appropriate Eureka skill.

Step 2: Read relevant source material

Before writing, read:

• The approved design document (for framing, hypotheses, gap)
• The hypothesis registration (for exact claims to support)
• The experiment plan (for what was actually done)
• Prior sections already written (for continuity and avoiding repetition)
• Result files relevant to this section
• The bibliography file (to know what references are available)

Step 3: Lock the narrative arc (Discovery-Adjusted Framing)

The brainstorming design document committed to a contribution altitude (method improvement / new framework / new phenomenon / falsification) and a story arc (problem-driven / opportunity-driven / surprise-driven / falsification-driven). See docs/references/narrative-guide.md — sections "Contribution altitude — 4 tiers" and "Story arc patterns — 4 shapes". Now that results exist, verify the original framing still fits — or discovery-adjust.

Run this 5-question check:

1. Strongest finding — what is the single strongest result in results/, measured by effect size, novelty, or surprise? State it in one sentence.
2. Frame match — does the original hypothesis (from the design doc) capture that finding? Or is a side finding stronger than the primary outcome?
3. Arc fit — does the original story arc (predicted in brainstorming) still work given what you actually found? If the prediction was confirmed → original arc likely stands. If a surprise came out → the arc may need to shift to surprise-driven or falsification-driven.
4. Altitude validity — is the altitude claimed in the design doc still defensible given the evidence collected? Flag altitude-evidence mismatch now, not at reviewer desk.
5. Commit — state in one paragraph: final altitude, final arc, one-sentence contribution statement. Recommended but not required: log this paragraph via eureka:research-journal (typically to docs/eureka/journal/YYYY-MM-DD.md) so the framing decision is traceable across sessions and audit. If you don't journal, at minimum paste the paragraph into your working notes or commit it as a top comment in main.tex/the manuscript entry point — the decision must be captured somewhere so future you (or a co-author) can see what was locked and why. All section writing flows from it.

HARKing guardrail — re-framing is not HARKing. The rule:

Pre-registration constrains the hypothesis; it does not constrain the story. Report the hypothesis faithfully in Methods and Results. Frame the paper around whatever the data actually shows.

See docs/references/narrative-guide.md — sections "Discovery-Adjusted Framing" for the full workflow, "Negative result reframing" (null → informative constraint), and "Venue-specific altitude tuning" if target venue has shifted since brainstorming.

When to re-fire this lock

The lock is "once per manuscript" by default. Re-fire it when any of these trigger:

1. eureka:novelty-competitive-audit returns CONCERN or BLOCK — the altitude or framing may need adjustment to maintain defensibility against recent literature
2. Target venue changes mid-project — different venues expect different altitudes; see narrative-guide.md section "Venue-specific altitude tuning"
3. Major result added or removed after the initial draft — the strongest finding may have shifted
4. Reviewer response revision — before writing a response letter and revised manuscript, re-examine framing in light of reviewer critique; a preempt surfaced by a reviewer should flow into novelty-competitive-audit + this re-fire
5. Explicit user request — if the narrative feels wrong mid-writing, re-fire

Re-fire = run the 5-question check above again, commit the new framing decision. The HARKing guardrail is unchanged: pre-registered hypothesis stays pinned (Methods + Results); only the narrative framing shifts.

Step 4: Write the section

Follow the Writing Discipline Rules above. Write the complete section.

Step 5: Inline self-check

Before dispatching the reviewer, do a quick pass:

• Every factual claim has a citation
• Every number has a source file (noted in comments)
• Every figure/table reference has a target
• Every variable in equations is defined
• Abbreviations spelled out on first use
• No TODO, XXX, [citation needed], placeholder content
• Section only discusses completed work (no "expected to show" in Results)

Step 6: Dispatch section-reviewer subagent

After the inline self-check passes, dispatch a fresh subagent for independent review:

1. Locate the reviewer prompt at skills/manuscript-writing/section-reviewer-prompt.md
2. Fill the placeholders:
   • {SECTION_PATH} → the file path of the section just written
   • {SECTION_NAME} → the section name (e.g., "Methods", "Results")
   • {BIBLIOGRAPHY_PATH} → the bibliography file path (.bib or references file)
   • {RESULTS_DIR} → the results directory path
   • {FIGURES_DIR} → the figures directory path
3. Dispatch via the Task tool (general-purpose subagent)
4. Wait for the reviewer to return Status: Approved or Status: Issues Found

Step 7: Act on reviewer feedback

• Status: Approved → move to the next section
• Status: Issues Found → fix each issue. Re-dispatch the reviewer. Repeat until Approved.

If the reviewer flags the same issue twice, escalate to the user.

Step 8: Move to next section

After the current section passes review, move to the next section whose prerequisite is met. Continue until all sections are complete.

After All Sections

Final pass

Read the complete manuscript from start to finish. Check for:

• Cross-section consistency (terminology, notation, abbreviation usage)
• Flow between sections (does the end of Methods lead naturally into Results?)
• Repetition (same claim made in Introduction and Discussion without adding interpretation)
• Forward references that are now resolvable

Write the Abstract

Only now. The Abstract summarizes the finished, reviewed manuscript. It should state:

1. The problem (1-2 sentences)
2. The approach (1-2 sentences)
3. The key results with specific numbers (2-3 sentences)
4. The implication (1 sentence)

The Abstract must independently make sense — a reader who reads only the Abstract should understand the contribution.

Transition to claims-audit

After the Abstract is written and the final pass is clean:

"All sections written and reviewed. Transitioning to eureka:claims-audit for full-manuscript verification."

Invoke eureka:claims-audit. That skill traces every number, verifies every figure, and checks that all experiments are reported (including negatives). manuscript-writing does per-section checking during writing; claims-audit does full-manuscript checking after writing.

Format Agnosticism

This skill works with any manuscript format:

For STEM research targeting top-tier journals (Nature family, Science family, Cell family, Brain, NeuroImage, JAMA, IEEE Transactions, etc.), LaTeX is the recommended default. Most top journals accept LaTeX submissions, BibTeX is the de facto citation management standard, and the section-file split pattern (paper/sections/NN-sectionname.tex) aligns naturally with this skill's per-section workflow. Use Markdown or other formats if your target venue requires them or your workflow is preprint-first / blog-style.

See docs/references/latex-guide.md for LaTeX conventions: main.tex template, section file structure, BibTeX key format, citation commands, math notation, figure/table commands, abbreviation rules, and the compile workflow.

The user specifies their format at the start of the writing session (or in CLAUDE.md). The discipline rules apply regardless — only the syntax changes.

Common Rationalizations

Red Flags — STOP

• Writing Results with "expected to show", "we anticipate", or "preliminary results suggest"
• Adding numbers not found in any results file
• Referencing figures that don't exist yet
• Writing a section whose prerequisite is not met
• Skipping the section-reviewer dispatch ("it's a short section, doesn't need review")
• Using passive voice to obscure who did what ("errors were observed" instead of "we observed errors in our preprocessing pipeline")
• Abstract being written before all sections are complete

Integration

• Called by: eureka:using-eureka when manuscript writing intent is detected
• Prerequisite: At least one section's prerequisites met
• Invokes: section-reviewer subagent (per section, after writing)
• Transitions to: eureka:claims-audit (after all sections + Abstract complete)
• Pairs with:
  • eureka:research-journal — capture writing decisions and framing locks
  • eureka:whats-next — if stuck on which section to write next
  • eureka:figure-design — when any section cites a figure that needs to be created or updated (fires automatically when manuscript-writing's Writing Discipline Rule 3 detects a figure citation without an existing artifact)
  • eureka:novelty-competitive-audit — pre-submission external novelty check; a CONCERN/BLOCK verdict triggers Step 3 re-fire
• Reference: docs/references/statistical-guide.md — Results section reporting standards, computational recipes (power, MDE, parametric uncertainty)
• Reference: docs/references/latex-guide.md — LaTeX conventions (main.tex template, section files, BibTeX, math notation, figures)
• Reference: docs/references/figure-guide.md — figure design conventions (chart type, typography, colorblind-safe palettes, journal export specs)
• Reference: docs/references/narrative-guide.md — Step 3 Discovery-Adjusted Framing, narrative arc selection, Intro-Discussion symmetry, venue-specific altitude tuning

Skill Type

FLEXIBLE — Section structure, length, format, and citation style adapt to the user's target journal and field. The discipline rules (prerequisites, traceability, citation, variable definitions, abstract-last) are fixed.