sciwrite-process skill

The writing process

Most of the pain people feel while writing comes from doing three different jobs at once. Separate them and the work gets faster and the result gets better.

Answer in whatever language the user writes to you in.

---

Three phases, and how the time should split

Pre-writing   70 %   gather, organise, work out the take-home messages
Drafting      10 %   compose prose, badly, quickly
Revision      20 %   where the elegance actually happens

Most people invert this, spending the bulk of their time on the drafting step. That is why writing feels awful: composing prose is the hardest, most attention-hungry part, and they are doing it for the longest, while also researching and editing at the same time.

When someone says they are stuck, ask which phase they are in. They usually turn out to be drafting without having pre-written — trying to compose sentences while hunting for the statistic that goes in them. Two sentences in thirty minutes, and no writing actually done.

---

Pre-writing (70 %)

The purpose is to have every fact at your fingertips and the shape of the piece decided before you open the blank document.

Gather into one place. Read your sources and pull out, as you go, every statistic, detail, quote and idea you might use — into a single ongoing document. It will get long (60 pages is normal for a feature). Keep the original sources filed in case you need them again.

Put borrowed passages in quotation marks as you paste them, so that months later you cannot mistake someone else's words for your own. This is the practical defence against accidental plagiarism, and it costs nothing at the time.

Then move the material around until everything belonging to one section sits together. This is where the organisation happens, and it is cheap here and expensive later.

Build a roadmap, not an outline. An outline with A/B/C and 1/2/3 is more trouble than it is worth. A roadmap lays out the sections in broad terms, and roughly what goes in each paragraph, with the relevant material already sitting under each heading. When you finally write, you are only putting known content into prose.

Think away from the computer. A blank document is a confining place to have ideas. Structure, take-home messages, the right word, the framing that makes the whole thing click — these tend to arrive while exercising, driving, waiting in line. Carry something to capture them with.

Two organisation rules that save whole revisions:

• Group like ideas. If the same topic appears in three paragraphs scattered through the paper, bring them together. Merging usually reveals repetition you could not see while they were apart.
• Do not bait-and-switch on controversies. Argument A, counter-A, rebuttal-A, then argument B, counter-B, rebuttal-B is exhausting to read. Put all the arguments, then all the counterarguments, then all the rebuttals.

For a manuscript specifically, pre-writing includes finalising the tables and figures — see sciwrite-manuscript.

---

Drafting (10 %)

Do not be a perfectionist here. This is the one instruction that matters.

The goal for a first draft is narrow and deliberately low: get the ideas down, in complete sentences, in the right order. That is all. The sentences do not have to sound good. They will not sound good.

Why the bar is set low: sentence-level problems are cheap to fix in revision. Structural problems — muddled take-home messages, wrong organisation — are expensive, because fixing them means rewriting everything downstream. So spend the draft on the expensive things and let the cheap ones be bad for now.

The other reason: this is the hardest step. Minimise time spent in it.

Sainani's own first drafts, from the course, contain the exact defects she teaches against — there is constructions, to be verbs, wordiness. They became good prose in revision. That is the process working, not failing.

When the task feels too big, shrink the goal. Today I will write 400 words. Choose a target so modest it cannot intimidate. What usually happens is you hit it in a couple of hours and keep going with momentum; and on the bad days, 400 words still counts as a successful day. Setting out to write the whole manuscript today guarantees you write nothing.

---

Revision (20 %)

Where the elegance comes from. Concrete techniques, in the order to apply them:

Read it out loud. The brain processes speech differently from text. Awkward rhythm, repetition and wordiness that are invisible on the page are obvious in the ear. Reading into a recorder and playing it back works even better.

Do the verb check. Take two or three paragraphs and underline the main verb of every sentence. Look at the list alone. How many to be verbs? How many passive? How many sit far from their subject? Changing four or five verbs often lifts a whole passage, and this takes two minutes.

Do the organisational review. Tag every paragraph in the margin with a short phrase naming its one idea. Then read only the tags. Repeated tags mean scattered material — move those paragraphs together and probably merge them. The tag sequence also shows you the logical flow at a glance, which prose does not.

Cut ruthlessly. Dead weight, blobs, long-for-short, jargon, acronyms, repetition, adverbs. See sciwrite-prose for the full passes and the lexicons.

Get outside eyes. Ask someone outside your niche — intelligent, scientific, not an expert in your area — to read it. Then ask them to tell you back three things: the main findings, the take-home message, and why the work matters. They should be able to do that without a technical background. Wherever they struggle, ask them to point at the sentences and paragraphs; those are where to spend your revision effort.

---

The final-draft checklist

Before it goes to a journal or a supervisor. See references/final-checklist.md for the full version; this is what it covers:

• Internal consistency. Nothing in one section contradicting another. The course's example: Methods says minimum two years of follow-up, Results says average follow-up 1.5 years. Both cannot be true, and a reviewer who sees it starts doubting everything.
• Numerical consistency. Abstract numbers matching body numbers; percentages matching raw counts; tables matching figures. Mismatches usually come from sloppy copy-paste or from re-running an analysis and updating only part of the manuscript — but what they look like from outside is several versions of the dataset in circulation.
• References that go somewhere. Check that each cited paper actually contains what you say it does. It very often does not.
• Primary sources. Do not inherit citations from other papers' reference lists. Statistics degrade as they propagate — the course traces a widely quoted prevalence figure back through fifty different attributions to three small 1980s surveys that could not support it.

Run the scripts:

# The scripts ship in sciwrite-prose/scripts/. Find that skill wherever it was
# installed: plugin, `npx skills add` (project or global), or a manual copy.
SCIWRITE=$(for d in "${CLAUDE_PLUGIN_ROOT:-.}/skills" .claude/skills .agents/skills \
                    ~/.claude/skills ~/.agents/skills; do
  [ -f "$d/sciwrite-prose/scripts/prose_audit.py" ] && { (cd "$d/sciwrite-prose/scripts" && pwd); break; }
done)

python "$SCIWRITE/numeric_consistency.py" paper.tex
python "$SCIWRITE/keyword_consistency.py" paper.tex
python "$SCIWRITE/prose_audit.py" paper.tex

If $SCIWRITE comes back empty, the sciwrite-prose skill is not installed: do these checks by reading, and tell the user that npx skills add dvdsosa/scientific-writing-skills adds the scripts.

---

Helping someone who is stuck

Diagnose before prescribing. The useful questions:

• What are you trying to say in this paragraph? If they cannot answer, that is the problem, and no amount of rewriting will fix it. Confusing prose is almost always unresolved thinking.
• Have you got your material organised, or are you looking things up as you write? If the latter, stop drafting and pre-write.
• Are you editing sentences as you write them? If so, that is why it is taking forever. Give them permission to write badly.
• Do the tables and figures exist yet? For a manuscript, drafting before they are settled means drafting twice.

Two things worth saying out loud when someone is anxious about writing:

Writing is hard for everyone, including people who do it professionally every day. Finding it difficult is not evidence of a deficiency.

Inspiration is not a prerequisite. Waiting to feel ready is procrastination with better branding. Being prepared — which is what pre-writing produces — is what actually makes writing possible.

---

Reference files

File	Read it when
references/final-checklist.md	a draft is close to submission

Related: sciwrite-manuscript for what goes in each section and the order to build them; sciwrite-prose for the revision passes in detail; sciwrite-publish for what happens after submission.