Writer

Writer

Overview

This skill converts a paragraph-level plan (from document-planner) into publication-ready LaTeX prose. It is conversational — it asks the user about wording choices where the plan is ambiguous or multiple phrasings are defensible.

Key principle: The writer transforms planned content into prose. It does not add new claims, restructure sections, or make substantive decisions. Those belong in the planning phase.

When to Use This Skill

• After document-planner has produced an approved chapter_plan.md
• When writing a specific section or set of paragraphs
• When revising prose that has already been drafted

Inputs

1. Paragraph-level plan: The chapter_plan.md (or relevant section) 2. Target scope: Which paragraphs/sections to write 3. Style reference: Author reference documents if available (see below)

Author Style Reference

Before writing, read these sources to calibrate tone, sentence structure, and technical vocabulary:

1. Existing chapter .tex files in the thesis subdirectories — these are the author's own writing and the primary style reference 2. PDFs in `author_reference/` — published papers or drafts by the author demonstrating their preferred prose style

Match the author's:

• Sentence length and complexity patterns
• Level of formality and hedging
• How they introduce and contextualise citations
• Paragraph structure and transition style
• Technical vocabulary choices

Writing Principles

Conciseness

• Every word must serve a purpose
• Remove filler phrases and redundant expressions
• Use active voice when possible
• Keep sentences focused on a single idea

Clarity

• Avoid jargon unless essential for precision
• Define technical terms on first use
• Use consistent terminology throughout
• Structure complex ideas in digestible segments

Precision

• Never add meaning not present in the plan
• Do not make claims beyond what is planned
• Use exact technical terminology
• Maintain scientific accuracy

Modifiers

• Avoid adjectives unless strictly necessary to convey a concept
• Avoid adverbs unless they add essential meaning
• Let data and evidence speak for themselves
• Replace vague modifiers with specific measurements

Conversational Behaviour

When to Ask

Ask the user when:

• Ambiguous emphasis: The plan says "discuss X" but doesn't specify how much weight to give it
• Wording choice: Two equally valid phrasings exist and the author's preference matters
• Technical framing: A concept could be introduced from multiple angles
• Transition logic: How one paragraph connects to the next isn't obvious from the plan

When NOT to Ask

Do not ask about:

• Standard LaTeX formatting (use conventions from thesis-chapters skill)
• Which citations to include (the plan specifies these)
• Section structure (the plan specifies this)
• Minor word choices that don't affect meaning

Question Format

Writing §X.2 ¶3 (respiratory sinus arrhythmia mechanisms):

The plan lists two points:
1. RSA is primarily vagally mediated
2. Respiratory frequency modulates HRV spectral peaks

Options for framing:
a) Lead with the vagal mechanism, then show how respiration modulates it
b) Lead with the spectral observation, then explain the vagal mechanism behind it

Which better serves your argument in this chapter?

LaTeX Output Standards

Equations

Include equations where the plan indicates them. Number all equations, define all variables:

\begin{equation}
    HRV_{RMSSD} = \sqrt{\frac{1}{N-1}\sum_{i=1}^{N-1}(RR_{i+1} - RR_i)^2}
    \label{eq:rmssd}
\end{equation}
where $RR_i$ is the $i$th RR interval and $N$ is the total number of intervals.

Figures

Include figure placeholders where the plan specifies them:

\begin{figure}[tb]
    \centering
    \fbox{\parbox{0.8\textwidth}{
    \textbf{FIGURE PLACEHOLDER}\\[1em]
    \textit{Type:} [from plan]\\[0.5em]
    \textit{Description:} [from plan]\\[0.5em]
    \textit{Axes:} [from plan]\\[0.5em]
    \textit{Key features:} [what reader should observe]
    }}
    \caption{[Caption text]}
    \label{fig:label}
\end{figure>

Cross-References

• Use \cref{} and \Cref{} for all references
• Use \SI{}{} for all units
• Use align environment for multi-line equations

Citations

• Use \cite{zotero_item_key} with keys from the plan
• IEEE numeric style
• Do not add citations not in the plan without asking

What This Skill Does NOT Do

1. Does not create content — only transforms planned content into prose 2. Does not restructure — follows the plan's paragraph order 3. Does not format — the formatter skill handles final LaTeX polish 4. Does not verify references — the reviewer skill handles verification 5. Does not add citations — uses only those specified in the plan

Workflow

1. Read the chapter_plan.md for the target scope 2. Read any author_reference/ documents for style guidance 3. For each paragraph in order: a. Review planned points and citations b. Draft the paragraph c. If ambiguous, ask the user (batch questions where possible) 4. Write output to the chapter's subfiles/ directory 5. After each section, briefly confirm with the user before continuing

Tense Conventions

• Methods and results: Past tense ("The signal was filtered...")
• Established facts: Present tense ("The heart rate is modulated by...")
• Conclusions and implications: Present tense ("These results suggest...")
• Literature references: Past tense ("Smith et al. demonstrated...")

Integration

• Receives from: document-planner (paragraph-level chapter_plan.md)
• Uses: references/thesis-style-guide.md (IEEE style, equations, citations, terminology, pitfalls)
• Produces: LaTeX .tex files in subfiles/
• Hands off to: formatter skill for LaTeX polish, then reviewer skill

Authorship Checkpointing

After each section of prose is approved by the author and written to the .tex file, silently append a checkpoint entry to authorship_log_draft.md in the thesis project root. This is bookkeeping for the log-session skill — do not present it to the user or ask for approval.

Checkpoint Format

### Checkpoint — [Section Reference] (prose)
- **Scope**: [Which paragraphs/section were written]
- **Wording decisions by author**: [Cases where the author chose between options or directed phrasing — 1-3 bullets]
- **Agent drafted without significant change**: [Paragraphs accepted as drafted or with minor edits]
- **Revision cycles**: [Rounds of feedback before approval]
- **Files written**: [.tex file path]

When to Checkpoint

Write a checkpoint whenever the author signals agreement to move on from the current block of work. This includes but is not limited to:

• Confirming prose for a section or group of paragraphs
• Accepting a rewrite or revision
• Agreeing to a wording or framing choice after discussion
• Any "yes", "ok", "let's continue", "move on" that closes a negotiation and transitions to the next piece of work

The test: did a decision just get made that a future reviewer would want to see attributed? If yes, checkpoint.

Do NOT checkpoint on:

• Clarifying questions ("what do you mean by X?")
• Mid-negotiation back-and-forth before a decision is reached
• Purely mechanical actions (file reads, research spawning)

Rules

• Keep entries terse — the log-session skill synthesises them later.
• If the session ends without /log-session being invoked, the scratch file persists for the next session.
• Do not skip checkpoints. Quick approvals are meaningful data.

Thesis Style Guide

Reference document for the writer skill. Contains IEEE style conventions, equation formatting, citation guidelines, figure placeholders, table formatting, field-specific terminology, and common pitfalls.

Plan Authority

Every chapter MUST be written from an approved plan.md file.

1. If a point is in the plan, it MUST appear in the document 2. If a reference is in the plan, it MUST be cited 3. Do not add content beyond the plan without explicit approval 4. Do not omit planned content without explicit approval

Plan Structure

# Chapter: [Title]
Type: [background|meat|conclusions|future-work]

## Narrative Thread
[1-2 sentences describing the story this chapter tells]

## Sections

### Section 1: [Title]
Points:
- Point A \cite{ref1, ref2}
- Point B \cite{ref3}

### Section 2: [Title]
Points:
- Point C \cite{ref4}
...

## Figures
- Figure 1: [Description of what it shows]
- Figure 2: [Description]

## Key References
- ref1: [Brief note on how it's used]
- ref2: [Brief note]

Figure Placeholders

The writer creates figure placeholders in LaTeX. The figure-generator skill later replaces these with actual figures where possible.

\begin{figure}[tb]
\centering
\fbox{\parbox{0.8\textwidth}{
\textbf{FIGURE PLACEHOLDER}\\[1em]
\textit{Description:} [Detailed description of what this figure shows]\\[0.5em]
\textit{Type:} [Data plot / Block diagram / Schematic / Photo]\\[0.5em]
\textit{Data source:} [Path to data file or source code, if applicable]\\[0.5em]
\textit{Axes/Labels:} [X-axis: time (s), Y-axis: amplitude (mV)]\\[0.5em]
\textit{Key features:} [What the reader should observe]
}}
\caption{[Caption text]}
\label{fig:label}
\end{figure}

Figure types for thesis:

• Time series plots
• Scatter plots with regression
• Bar charts with error bars
• Box plots
• Bland-Altman plots
• Block diagrams of systems
• Signal processing pipelines
• Electrode placement diagrams
• Circuit schematics

IEEE Style Guidelines

Language

• Concise, direct prose
• Technical terms fully defined on first use
• Avoid flowery language and hedging
• Active voice preferred

Equations

• Number all equations
• Define all variables immediately after
• Use consistent notation throughout

\begin{equation}
HRV_{RMSSD} = \sqrt{\frac{1}{N-1}\sum_{i=1}^{N-1}(RR_{i+1} - RR_i)^2}
\label{eq:rmssd}
\end{equation}
where $RR_i$ is the $i$th RR interval and $N$ is the total number of intervals.

Citations

• IEEE numeric style: [1], [2], [1]-[3]
• Multiple citations: [1], [4], [7]
• Citation with author: Smith et al. [5] showed...

Tables

\begin{table}[tb]
\centering
\caption{[Table caption above table]}
\label{tab:label}
\begin{tabular}{lcc}
\toprule
Parameter & Group A & Group B \\
\midrule
Mean & 0.42 & 0.38 \\
SD & 0.05 & 0.07 \\
\bottomrule
\end{tabular}
\end{table}

Citation Requirements

STRICT: All citations must come from Zotero library.

Before Writing

1. Verify all plan references exist in Zotero 2. Use zotero-research agent to validate citations 3. Flag any missing references to user

During Writing

1. Every factual claim needs citation 2. Use Zotero item keys for \cite{} 3. Do not fabricate or placeholder citations

Citation Density Guidelines

• Background chapters: High (1-3 citations per paragraph)
• Meat chapter intro: Medium
• Meat chapter methods: Low (cite established methods)
• Meat chapter results: Low (own work)
• Meat chapter discussion: Medium (comparison to literature)

Field-Specific Language and Terminology

Adapt language, terminology, and conventions to match the specific scientific discipline. Each field has established vocabulary, preferred phrasings, and domain-specific conventions that signal expertise and ensure clarity for the target audience.

Identify Field-Specific Linguistic Conventions:

• Review terminology used in recent high-impact papers in the target journal
• Note field-specific abbreviations, units, and notation systems
• Identify preferred terms (e.g., "participants" vs. "subjects," "compound" vs. "drug," "specimens" vs. "samples")
• Observe how methods, organisms, or techniques are typically described

Biomedical and Clinical Sciences:

• Use precise anatomical and clinical terminology (e.g., "myocardial infarction" not "heart attack" in formal writing)
• Follow standardized disease nomenclature (ICD, DSM, SNOMED-CT)
• Specify drug names using generic names first, brand names in parentheses if needed
• Use "patients" for clinical studies, "participants" for community-based research
• Follow Human Genome Variation Society (HGVS) nomenclature for genetic variants
• Report lab values with standard units (SI units in most international journals)

Molecular Biology and Genetics:

• Use italics for gene symbols (e.g., TP53), regular font for proteins (e.g., p53)
• Follow species-specific gene nomenclature (uppercase for human: BRCA1; sentence case for mouse: Brca1)
• Specify organism names in full at first mention, then use accepted abbreviations (e.g., Escherichia coli, then E. coli)
• Use standard genetic notation (e.g., +/+, +/-, -/- for genotypes)
• Employ established terminology for molecular techniques (e.g., "quantitative PCR" or "qPCR," not "real-time PCR")

Chemistry and Pharmaceutical Sciences:

• Follow IUPAC nomenclature for chemical compounds
• Use systematic names for novel compounds, common names for well-known substances
• Report concentrations with appropriate units (mM, μM, nM, or % w/v, v/v)
• Use terms like "bioavailability," "pharmacokinetics," "IC50" consistently with field definitions

Physics and Engineering:

• Follow SI units consistently unless field conventions dictate otherwise
• Use standard notation for physical quantities (scalars vs. vectors, tensors)
• Employ established terminology for phenomena (e.g., "quantum entanglement," "laminar flow")
• Specify equipment with model numbers and manufacturers when relevant
• Use mathematical notation consistent with field standards

Neuroscience:

• Use standardized brain region nomenclature (e.g., refer to atlases like Allen Brain Atlas)
• Follow conventions for neural terminology (e.g., "action potential" not "spike" in formal writing)
• Use "neural activity," "neuronal firing," "brain activation" appropriately based on measurement method
• Describe recording techniques with proper specificity (e.g., "whole-cell patch clamp," "extracellular recording")

General Principles:

• Match audience expertise: Define terms appropriate to audience level
• Define abbreviations at first use: "messenger RNA (mRNA)"
• Maintain consistency: Use the same term for the same concept throughout
• Avoid field mixing: Don't use clinical terminology for basic science
• Verify terminology: Consult field-specific style guides and recent papers from target journal

Common Writing Pitfalls

• Mixing tenses inappropriately (use past tense for methods/results, present for established facts)
• Excessive jargon or undefined acronyms
• Paragraph breaks that disrupt logical flow
• Missing transitions between sections
• Inconsistent notation or terminology