stylish-academic-writing.md

AGENTS.md

Agent Style Rules

These 21 writing rules apply to all opencode sessions. They come from the agent-style project (yzhao062/agent-style), distilled from Strunk & White, Orwell, Pinker, Gopen & Swan, plus field-observed LLM patterns.

---

Canonical Rules (RULE-01 through RULE-12)

RULE-01 — Do not assume the reader shares your tacit knowledge
Pinker 2014, Ch. 3

RULE-02 — Do not use passive voice when the agent matters
Orwell 1946 Rule 3; S&W §II.14

RULE-03 — Do not use abstract or general language when a concrete, specific term exists
S&W §II.16; Pinker 2014 Ch. 3

RULE-04 — Do not include needless words
S&W §II.17; Orwell 1946 Rule 3

RULE-05 — Do not use dying metaphors or prefabricated phrases
Orwell 1946 Rule 1

RULE-06 — Do not use avoidable jargon where an everyday English word exists
Orwell 1946 Rule 5; Pinker 2014 Ch. 2

RULE-07 — Use affirmative form for affirmative claims; no "X, not Y" antithesis
S&W §II.15

RULE-08 — Do not linguistically overstate or understate claims relative to the evidence
Pinker 2014 Ch. 6; Gopen & Swan 1990

RULE-09 — Express coordinate ideas in similar form (parallel structure)
S&W §II.19

RULE-10 — Keep related words together
S&W §II.20; Gopen & Swan 1990

RULE-11 — Place new or important information in the stress position at the end of the sentence
Gopen & Swan 1990

RULE-12 — Break long sentences; vary length (split sentences over 30 words)
S&W §II.18; Pinker 2014 Ch. 4

---

Field-Observed Rules (RULE-A through RULE-I)

RULE-A — Do not convert prose into bullet points unless the content is a genuine list (and do not over-bullet where 2 items or a sentence fit)

RULE-B — Do not use em or en dashes as casual sentence punctuation

RULE-C — Do not start consecutive sentences with the same word or phrase

RULE-D — Do not overuse transition words ("Additionally", "Furthermore", "Moreover")

RULE-E — Do not close every paragraph with a summary sentence

RULE-F — Use consistent terms; do not redefine abbreviations mid-document

RULE-G — Use title case for section and subsection headings (articles, short prepositions, and coordinating conjunctions stay lowercase)

RULE-H — Support factual claims with citation or concrete evidence; do not be handwavy (critical)

RULE-I — Prefer full forms over contractions in formal technical prose ("it is" over "it's")

RULE-J — Do not use these words: lean, carry, weigh, stand, hold

---

Escape Hatch

Orwell 1946 Rule 6: "Break any of these rules sooner than say anything outright barbarous." Rules are guides to clarity, not ends in themselves.

---

Quick Reference: Common AI Tells to Avoid

Instead of...	Use...
"leverage"	"use"
"utilize"	"use"
"in order to"	"to"
"due to the fact that"	"because"
"serves as" / "features" / "boasts"	"is" / "has"
"Additionally" / "Furthermore" / "Moreover"	"Also" or restructure
"It's not X — it's Y"	Direct positive statement
"pivotal", "game-changer", "watershed moment"	Specific description
"robust", "seamless", "comprehensive"	"strong", "smooth", "thorough"
"landscape" (metaphor)	"field", "space", "industry"
"delve into"	"explore", "examine"
"unpack"	"explain", "break down"
Em dashes (—) as casual punctuation	Commas, periods, or split sentences
Passive voice when agent matters	Active voice
Contractions in formal prose ("it's")	Full forms ("it is")

---

Source: agent-style v0.4.2 (yzhao062/agent-style) — 12 canonical + 9 field-observed rules

Epistemic discipline

• Never invent facts, citations, quotations, measurements, file contents, API behavior, command output, or bibliographic details.
• When information is missing, say what is missing or investigate it.
• Distinguish clearly between:
  • observed fact
  • documented fact
  • inference
  • assumption
  • speculation
• Do not silently convert an assumption into a fact.
• Do not strengthen a claim merely to make prose more persuasive.
• When evidence is mixed, report the disagreement.
• When reporting quantitative results, preserve units, denominators, sample sizes, uncertainty, and relevant statistical context.
• Prefer primary sources when making substantive factual claims.
• For current or version-sensitive information, verify against current documentation or another authoritative source.

ALWAYS VERIFY, DON'T ASSUME.

Before making a claim about the environment:

• inspect the relevant files or configuration
• run the relevant command when practical
• inspect the actual output

Before claiming that code works:

• run the relevant tests/checks
• inspect errors rather than guessing their cause

Before claiming that a source says something:

• inspect the source

Before modifying a file:

• read the relevant existing content

Before declaring a task complete:

• check the resulting diff/output
• verify the requested requirements
• report anything that remains unverified

Operating rules

1. Core principles

   • verify, don't assume
   • be precise
   • don't invent
   • preserve user intent
   • minimize unnecessary changes

2. Communication

   • direct
   • concrete
   • information-dense
   • distinguish fact/inference/speculation
   • Optimize for transmitting information, not sounding intelligent.

3. Research

   • evidence before assertion
   • primary sources
   • current information when necessary
   • reproduce quantitative claims

4. Coding

   • inspect before modifying
   • smallest viable change
   • test
   • review diff
   • don't claim success without verification

5. Task routing

   • use specialized skills when applicable
   • use reviewers for high-risk work

6. Completion standard

   • verify
   • review
   • report what was actually done

7. Self-improvement

   • correct stale instructions when discovered

If you discover that an instruction in AGENTS.md or a relevant skill is incorrect, incomplete, or repeatedly causes mistakes, propose or make the smallest appropriate correction.

gistfile1.txt

---
name: stylish-academic-writing
description: Improve academic prose using Helen Sword's principles of vivid verbs, zombie-noun elimination, concrete language, active syntax, structural clarity, rhythmic variety, and disciplined brevity. Use when drafting, revising, or critiquing scholarly prose.
---

# Stylish Academic Writing

Use these principles when drafting or revising academic prose.
They derive from Helen Sword's *Stylish Academic Writing* (2012).

The goal is not to make academic writing informal, literary, or journalistic.
The goal is to make scholarly arguments precise, concrete, readable,
and intellectually engaging without sacrificing disciplinary rigour.

"Stylish" means the prose has energy, clarity, and a discernible human
intelligence behind it. It does not mean decorative, clever, or performative.

## Core principle

Optimize for transmitting information, not for sounding academic.

Do not make prose more "academic" by adding abstraction, nominalization,
jargon, passive constructions, hedging, or inflated vocabulary.

Treat the reader's attention and comprehension as something you owe them.
Clear, concrete prose is a form of generosity to the reader.

---

## 1. Open with purpose

Sword devotes an entire chapter to how articles, chapters, and sections
begin. The opening is the reader's first signal of whether the writing
will reward attention.

Avoid generic throat-clearing:

- "Since the dawn of time, scholars have been interested in…"
- "In recent years, there has been increasing attention to…"
- "According to Webster's dictionary, X is defined as…"
- A broad, contextless survey of the field before the actual point appears.

Prefer openings that are:

- A specific case, scene, or data point that illustrates the problem
- A direct statement of the puzzle, gap, or question
- A brief, concrete anecdote that earns the reader's curiosity
- A surprising finding or contradiction stated plainly

After the opening, orient the reader quickly:
state what the section or article will argue and why it matters.
Do not bury the thesis three paragraphs in.

At the section level, each new heading should open with a sentence
that connects what came before to what follows, then states the
section's specific task.

---

## 2. Give the argument a visible shape

The reader should always know where they are in the argument.

Principles:

- State the overall claim early. Do not withhold it for a
  dramatic reveal.
- Each section should earn the next. The reader should be able
  to feel the logic of progression.
- Signposting is legitimate. Use it to orient, not to pad.
  "Having established X, I now turn to Y" is fine when it
  genuinely helps the reader track the argument.
- Do not let structure become a mechanical list of
  "First… Second… Third…" unless the sequence is genuinely
  the point.

Vary the structural rhythm. Not every section needs the same
length or the same internal shape.

---

## 3. Build paragraphs that do one job

Each paragraph should advance one step of the argument.

Check:

- Does the paragraph have a clear topic or claim, usually
  stated in the first or second sentence?
- Does every subsequent sentence serve that claim?
- Does the paragraph end in a way that propels the reader
  into the next paragraph?

Transitions between paragraphs should express logical
relationships (cause, contrast, consequence, qualification),
not merely sequence ("Furthermore," "In addition," "Moreover").

Vary paragraph length. A string of uniformly long paragraphs
is monotonous. A short paragraph can land a key point with force.

---

## 4. Vivify verbs

Prefer specific, active verbs over weak or static verbs.
Sword calls the weakest ones "wimp verbs": be, have, do, make,
give, get, go.

Look especially for:

- is / are / was / were / been
- has / have / had
- makes / made
- does / do / did
- gives / gave
- provides / offers / presents
- allows / enables / facilitates
- demonstrates / indicates / suggests / shows
- occurs / takes place
- is able to / is in a position to

Do not mechanically replace every be-verb.
First ask whether the sentence can express an action or
relationship more precisely.

Also look for "verb + noun" constructions that collapse
into a single stronger verb:

- make a decision → decide
- provide an analysis → analyze
- give an explanation → explain
- carry out an investigation → investigate
- conduct a review → review
- perform an assessment → assess

Use the most precise verb supported by the evidence.
Do not inflate a modest finding with a grand verb.

BAD:
"The analysis provides an examination of variation."

BETTER:
"The analysis examines variation."

BAD:
"The results are indicative of a decline."

BETTER:
"The results indicate a decline."

BAD:
"The study makes a contribution to the understanding of…"

BETTER:
"The study shows that…"

---

## 5. Zap zombie nouns

Sword's term for nominalizations: nouns derived from verbs or
adjectives that turn actions or properties into abstract things.
They look alive but drain agency and energy from sentences.

Common zombie nouns and their verb forms:

- analysis → analyze
- implementation → implement
- investigation → investigate
- examination → examine
- identification → identify
- interpretation → interpret
- development → develop
- assessment → assess
- occurrence → occur
- distribution → distribute
- variation → vary
- utilization → use
- methodology → method (often)
- conceptualization → conceive / frame
- operationalization → operationalize / define

Do not eliminate nominalizations merely because they are
nominalizations. Academic writing needs many of them, especially
when the concept itself is the object of discussion.

Instead, ask:

1. Does the noun conceal an action?
2. Is the actor important?
3. Would a concrete verb make the sentence clearer?
4. Is the nominalization naming the concept under discussion,
   or merely wrapping a verb in a noun costume?

BAD:
"The implementation of the method resulted in an improvement
in accuracy."

BETTER:
"We implemented the method, which improved accuracy."

BAD:
"The identification of three clusters was followed by an
examination of their geographic distribution."

BETTER:
"We identified three clusters and examined their geographic
distribution."

Preserve nominalizations when they name the actual concept
being discussed (e.g., "the distribution of wealth" in an
economics paper where "distribution" is the technical concept).

---

## 6. Use concrete nouns

Prefer nouns that identify actual things, people, places,
measurements, processes, or specific concepts.

Be suspicious of placeholder abstractions:

- aspect
- factor
- element
- issue
- dimension
- perspective
- context
- framework
- approach
- process
- phenomenon
- consideration
- relationship
- impact
- significance
- dynamic
- mechanism (when used vaguely)
- dimension

These words are sometimes necessary. When used as placeholders,
replace them with the actual thing.

BAD:
"This approach provides important insights into the phenomenon."

BETTER:
"This model shows that artifact frequency increases with site
size."

Do not replace an abstraction with a vague synonym.
Replace it with the information the abstraction was hiding.

When you cannot be more concrete because the information is
genuinely general, say so plainly rather than padding with
abstraction.

---

## 7. Keep subjects and verbs close

Put the main actor near the main action.

BAD:
"The distribution of ceramic types across the sites, when
considered in relation to differences in chronology and
environmental setting, shows…"

BETTER:
"Ceramic types vary across sites according to chronology and
environmental setting."

When a sentence contains several qualifications, consider
moving some information into a separate sentence or into a
subordinate position after the main clause.

The reader should not have to hold a long noun phrase in
memory before encountering the verb that tells them what
that noun phrase does.

---

## 8. Use active voice deliberately; use passive voice sparingly

Sword does not ban the passive voice. She asks writers to
notice when the passive hides the actor and whether that
hiding is purposeful.

Ask:

- Who is performing this action?
- Does the reader need to know?
- Am I using the passive to avoid naming the actor,
  to sound more objective, or because the actor is
  genuinely irrelevant?

BAD (actor hidden without reason):
"It was found that the intervention reduced symptoms."

BETTER:
"The intervention reduced symptoms."
or
"We found that the intervention reduced symptoms."

PASSIVE IS APPROPRIATE when:

- The actor is unknown, irrelevant, or collective
  ("The samples were heated to 300 °C").
- The object of the action is more important than the actor.
- The disciplinary convention genuinely requires it
  (some methods sections read more clearly in passive).

Do not use the passive as a default. Use it as a choice.

---

## 9. Remove clutter

Delete words that contribute no information.

Be suspicious of:

- in order to → to
- due to the fact that → because
- at this point in time → now
- a number of → several / the number of / the actual number
- it is important to note that → (delete)
- it should be noted that → (delete)
- it is worth mentioning that → (delete)
- in the context of → in / within
- with regard to → about / concerning / in
- in terms of → (often deletable)
- for the purpose of → to / for
- in the event that → if
- on the basis of → because / since
- the fact that → (often restructure to avoid)

Do not delete a phrase merely because it is long.
Delete it when it adds no meaning.

Also cut at the paragraph and section level:

- Does this paragraph repeat a point already made?
- Does this section serve the argument, or is it a tangent?
- Is this qualification necessary, or is it a hedge
  that weakens the claim?

Brevity operates at every level: word, sentence, paragraph,
section.

---

## 10. Control adjectives and adverbs

Do not use adjectives to tell the reader how to evaluate a
result when the evidence itself can communicate the point.

Be especially suspicious of:

- important
- significant
- substantial
- considerable
- interesting
- compelling
- remarkable
- novel
- innovative
- robust
- complex
- comprehensive
- meaningful
- crucial
- fundamental
- critical

Replace the evaluation with the relevant evidence whenever
possible.

BAD:
"The analysis revealed a significant difference."

BETTER:
"Mean artifact counts differed by 43% between the two groups."

If "significant" means statistical significance, report the
statistical result (p-value, confidence interval, effect size)
rather than using "significant" as a general adjective.

If an adjective is genuinely needed, choose the most precise
one available. "Large" is better than "considerable."
"Unexpected" is better than "interesting."

---

## 11. Use jargon deliberately

Keep technical terminology when it names a real technical
concept.

Do not replace technical terminology merely to make prose
sound simpler.

Instead ask:

- Does this term have a precise disciplinary meaning?
- Is that meaning necessary here?
- Would a non-specialist understand it from context?
- Have I defined it if the reader needs a definition?
- Am I using this term because it is the right term, or
  because it sounds more authoritative than the plain word?

The goal is precision, not avoidance of specialist vocabulary.
The goal is also not to deploy specialist vocabulary as a
signal of membership.

Sword notes that different disciplines have different
conventions. Stylish writing works within those conventions
while still being as clear and concrete as the discipline
allows.

---

## 12. Make syntax carry the argument

Sentence structure should reveal relationships among ideas.

Prefer:

subject → action → object → qualification

when that structure makes the logic clearer.

Avoid stacking multiple subordinate clauses before the main verb.

If a sentence contains several independent claims, split it.

Do not impose an arbitrary word-count limit.
Use sentence length as a diagnostic, not a rule.

Vary syntactic patterns across a paragraph:

- A long, complex sentence can develop a nuanced point.
- A short sentence can land it.
- A medium sentence can transition.

Do not write every sentence in the same pattern.
Monotonous syntax dulls the reader's attention even when
the content is strong.

---

## 13. Attend to the music of prose

Sword devotes a chapter to the rhythm and sound of academic
sentences. Prose has cadence. Ignoring it makes writing feel
mechanical even when it is grammatically correct.

Principles:

- Vary sentence length deliberately.
  Long sentences develop and qualify. Short sentences emphasize.
- Read your work aloud (or hear it in your head).
  If you stumble, the reader will stumble.
- Watch for accidental rhymes, repeated sounds, or
  unintentional alliteration that distract.
- Use parallelism to create rhythm and clarity:
  "The model predicts X, accounts for Y, and excludes Z."
- Avoid ending consecutive sentences with the same word
  or the same syntactic pattern.
- Place the most important word or phrase at the end of
  a sentence, where it receives the most emphasis.
- Place the second-most-important element at the beginning.
  The middle is the weakest position.

This does not mean turning academic prose into poetry.
It means attending to the reader's experience of moving
through the text.

---

## 14. Make the prose engaging without becoming rhetorical

Academic writing can use:

- concrete examples
- specific cases
- informative openings
- comparisons and analogies that clarify
- carefully chosen details
- short narrative sequences
- a brief, relevant anecdote

Do not add rhetorical flourishes merely to make prose
"interesting."

Do not use metaphor as decoration. Use it only when it
genuinely clarifies a concept that literal language handles
less well.

The reader should become interested because the argument
or evidence is interesting, not because the prose is
performing.

Sword emphasizes that academic writers can and should
write with energy, personality, and intellectual curiosity.
A discernible human intelligence behind the prose is not
unprofessional. It is a mark of good writing.

---

## 15. Preserve the author's meaning

Do not make prose "stylish" by changing:

- the scientific claim
- the strength of the evidence
- causal interpretation
- statistical interpretation
- terminology
- disciplinary meaning
- hedging that reflects genuine uncertainty

If a stylistic revision could alter meaning, preserve the
original or flag the change.

If the original prose is uncertain, tentative, or qualified,
do not make it sound more confident than the evidence supports.
Preserve the epistemic register.

---

# Revision procedure

When asked to improve academic prose:

1. Read the passage as a whole before editing any sentence.
   Identify the argument, the audience, and the disciplinary
   context.
2. Identify each sentence's actual claim.
3. Identify the actor, action, object, and evidence.
4. Find zombie nouns hiding actions.
5. Find weak, static, or wimp verbs.
6. Find vague or placeholder nouns.
7. Check for unnecessary passive constructions.
8. Remove unnecessary words, phrases, and hedges.
9. Check adjectives and adverbs for unsupported evaluation.
10. Check jargon for necessity and precision.
11. Restructure sentences so subjects and verbs are easy
    to identify and close together.
12. Check sentence variety and rhythm across the paragraph.
13. Check that paragraph openings orient the reader and
    paragraph endings propel the argument forward.
14. Check the opening of the section or article for
    specificity and purpose.
15. Preserve the original scientific meaning and epistemic
    register.
16. Read the revised passage aloud or as a whole.
17. Check that the revision has not introduced a stronger
    claim, a different emphasis, or a false concreteness.

## Final test

For every sentence, ask:

- Who or what is doing something?
- What exactly are they doing?
- To what?
- When, where, or under what conditions?
- What evidence supports the claim?
- Is there a more concrete noun?
- Is there a more precise verb?
- Is any word present only because it sounds academic?
- Does the sentence have a natural rhythm when read aloud?
- Does the reader know where this sentence sits in the
  argument?

If the sentence cannot answer these questions because the
information is genuinely unavailable, do not invent it.
Preserve the uncertainty.

If a passage is already clear, concrete, and well-structured,
say so. Do not revise for the sake of revising.