angushushu/shu-academic-writing-skill / core/engineer-argument
engineer-argument
VerifiedDiagnose why a draft will not land with its readers, using Larry McEnerney's framework — value over clarity, reader-driven prose, instability and cost, community codes. Use when someone shares a paper, abstract, introduction, dissertation chapter, literature review, grant or research proposal, or conference submission and wants feedback, review, critique, or "does this work?" — and when they ask why their writing gets rejected, desk-rejected, ignored, or called boring or unconvincing, how to make an argument compelling, whether their contribution is significant enough, or how to write a stronger intro or abstract. This is the top-down structural review: value, problem, movement, code, and the sentence patterns that follow. For a pure line-level pass on prose whose argument is already settled, read `core/polish-prose/SKILL.md` instead. Default behavior is diagnosis and coaching, never rewriting.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.8 KB |
| references/argument-patterns.md | markdown | 4.2 KB |
| references/diagnostics.md | markdown | 10.6 KB |
| references/drills.md | markdown | 6.1 KB |
| references/genres.md | markdown | 9.2 KB |
| references/principles.md | markdown | 16.2 KB |
| references/sentence-patterns.md | markdown | 5.1 KB |
references/principles.md
View on GitHub# The Principles
Larry McEnerney's framework, as taught in the University of Chicago Writing Program and in his
widely circulated talk on writing effectively. Paraphrased throughout — apply the ideas, don't
recite them.
## Contents
1. [The three functions of writing](#1-the-three-functions-of-writing)
2. [Why school ruined you](#2-why-school-ruined-you)
3. [Value beats clarity](#3-value-beats-clarity)
4. [Who your readers actually are](#4-who-your-readers-actually-are)
5. [Instability and cost: the engine](#5-instability-and-cost-the-engine)
6. [Gap ≠ problem](#6-gap--problem)
7. [Stasis is not background](#7-stasis-is-not-background)
8. [Movement, not exposition](#8-movement-not-exposition)
9. [The code](#9-the-code)
10. [Clarity is not in the text](#10-clarity-is-not-in-the-text)
11. [Two drafts, two audiences](#11-two-drafts-two-audiences)
12. [Common objections](#12-common-objections)
---
## 1. The three functions of writing
Writing does three things, and they are not equally useful to you.
1. **It helps you think.** Real and valuable — most people don't know what they think until
they write it. But this draft is *for you*. It is a thinking instrument, not a document.
2. **It communicates your ideas.** This is what most writers believe they're doing. It is also
why most professional writing fails, because nobody outside school has agreed to receive
your ideas.
3. **It changes what readers believe.** This is the only function that matters professionally.
Almost every diagnosable problem in an academic draft comes from shipping a function-1
document while believing it is a function-3 document. The author has written to work out their
own understanding and then submitted it. It reads as a record of thinking rather than an
intervention in a conversation.
**Diagnostic signature of a function-1 draft:** chronological structure ("first I looked at X,
then I found Y"), exhaustive coverage, background that establishes context nobody asked for,
findings reported in the order discovered, a conclusion that finally states the interesting
thing.
## 2. Why school ruined you
For sixteen-plus years someone was **paid to read your writing.** That teacher read every
word, in order, to the end, whether or not it was any good — and their job was to assess
whether *you* had learned something. That arrangement taught habits that are actively harmful
afterward:
| School habit | Why it worked then | Why it fails now |
|---|---|---|
| Demonstrate what you know | The reader was grading your knowledge | Nobody is grading you; showing your work is a cost, not a benefit |
| Cover the topic thoroughly | Completeness signaled effort | Experts skip everything they already know |
| Explain from general to specific (funnel intro) | Teacher wanted context established | Experts have the context; the funnel wastes the only paragraph they'll read |
| Define your terms | Proved you understood them | Defining a term your readers use daily marks you as an outsider |
| Write clearly and be correct | Correctness was the grade | Correct and clear is not the same as *worth reading* |
| Fill a gap in the literature | Gap-filling looked like contribution | A gap is only interesting if leaving it open costs someone something |
The deepest damage: school taught that writing's purpose is to **display competence to an
evaluator.** In the professional world the reader is not evaluating you; they are looking for
something they can use. Competence is assumed; it earns nothing.
**When reviewing, name the school habit explicitly.** Writers recognize themselves in it, and
naming it does more for the next draft than fixing this one.
## 3. Value beats clarity
Rank the criteria a reader applies:
1. **Valuable** — does this change something for me?
2. **Clear** — can I process it without effort?
3. **Organized** — can I find my way?
4. **Persuasive** — do I believe it?
Value dominates. Experts will fight through genuinely difficult prose if it's valuable, and
will abandon perfectly clear prose that isn't. Writers invert this constantly: they polish
sentences on a draft that has nothing at stake.
**The value test.** In one sentence: *before reading this, these specific readers believed X;
after, they believe Y.* If the author can only produce "readers will learn about X," there is
no value — that's a topic, not a change. If they produce "readers will learn that X is more
complicated than they thought," push harder: complicated *how*, and what does the complication
cost them?
Note the phrasing: value is not "new," not "true," not "interesting to me," and not "important
in general." **New is not valuable.** You can produce endless novel true facts nobody needs.
Value = it changes the beliefs or the work of a specific community.
## 4. Who your readers actually are
Build your diagnosis on an accurate model of the reader. Experts in your field:
- **Are not paid to read you.** They quit the moment cost exceeds expected return.
- **Read fast and non-linearly.** Title, abstract, first line of paragraphs, figures,
conclusion. They may never read your section 2.
- **Already know the background.** Everything they know that you explain is a withdrawal from
your credibility account.
- **Are resistant.** They have their own commitments and would rather not revise them.
- **Read to use, not to understand.** They're scanning for what they can take, cite, apply,
or argue against. "Reading to understand" is a student's mode; "reading to use" is a
professional's.
- **Are a specific, nameable group** — not "the general reader," not "an educated audience."
The community that shares the problem is the community that can grant value.
Consequence: writing that assumes a patient, receptive, well-disposed reader is
mis-engineered. Ask of every paragraph, *why would someone who is skimming and slightly
annoyed keep going here?*
## 5. Instability and cost: the engine
Readers keep reading when something is unstable — when something they believe, or believe
they know, is under threat. The move is not "here's my topic"; it's **"something you think is
settled isn't."**
The engine has four parts:
1. **Stability.** What the community currently holds. Brief — one or two sentences. Not a
literature review, and not general context. State it *because you're about to break it.*
2. **Destabilization.** The "but." An anomaly, a contradiction, an inconsistency, a puzzling
result, a case the accepted account can't handle. This must be a problem *for them*, in
their terms.
3. **Cost.** So what? What follows from leaving it unresolved — bad inferences, wasted effort,
a misdiagnosed mechanism, a policy built on a false premise, a whole line of work resting
on something that doesn't hold. **This is the step writers skip, and it's the step that
creates value.**
4. **Resolution.** Your claim, promised early.
Steps 1–3 belong in the opening, not on page 8. If a reader has to reach the discussion
section to find out why any of this matters, they didn't.
**Language of instability.** Real destabilization leaves lexical traces: *but, however, yet,
although, despite, whereas, surprisingly, puzzlingly, anomalous, paradox, tension,
inconsistent, contradicts, fails to account for, cannot explain, overlooked, unresolved, at
odds with.* A draft opening with near-zero density of these words is almost certainly a topic
tour. Count them — the script does this — and read the count against the section's job.
**Language of cost.** *At stake, consequence, risk, otherwise, unless, we cannot, misleads,
undermines, rests on, depends on.* Distinguish these from cheap importance words —
*important, significant, crucial, key, essential* — which assert value without demonstrating
it and are usually a signal that the author has not worked out the stakes.
## 6. Gap ≠ problem
The single most common failure in academic writing:
> "X has been studied extensively, but little attention has been paid to Y. This paper
> examines Y."
Nobody cares. The unexamined is infinite. A gap becomes a problem only when you show what the
community loses by it remaining open. Test with a hostile "so what?":
- Gap: nobody has studied Y. → *So what?*
- Problem: our accepted account of X assumes Y behaves a certain way; if it doesn't, the
conclusions drawn from a decade of X-research don't hold.
Same missing literature; only the second gives a reason to read. When you find gap-framing in
a draft, quote it, apply the hostile "so what?", and ask the author to answer it — do not
answer it for them. Often they *can*, immediately, and the answer was in their head the whole
time. That moment is the most valuable thing a review produces.
## 7. Stasis is not background
Writers confuse these constantly, and the confusion is what produces an introduction with no
value in it.
**Background** is what you give readers so they can build on it. You want them to accept it.
It must stay stable — the last thing you want is a reader doubting your background.
**Stasis** is the opposite, and the name is ironic. Stasis is what you introduce *in order to
knock down*. You present the settled view precisely so that you can show it does not hold. It
looks stable at the start of the introduction; by the end, it is not stable at all. It is not a
foundation, it is the source of the problem.
An introduction built on background explains. An introduction built on stasis moves. Only the
second creates a reason to keep reading.
**The four stability devices.** Most valueless introductions are built from one of these. Each
is legitimate in its place; each becomes a problem when it arrives *before* the reader has been
given a reason to care.
1. **History or background** — a short (or long) account of how the topic developed.
2. **Definitions** — offered as settled, certain, uncontroversial ground.
3. **A method or analytic approach** — presented as an accepted underlying certainty, so that
results produced by it inherit that legitimacy.
4. **An opening generalization** — a general truth, with the paper's idea presented as an
instance of it.
None of these is bad writing. All four are ways of establishing that knowledge is cumulative,
which it often is. But all four are moves toward stability, and stability is not value. When
you find a draft opening with one of them, the diagnostic question is not "is this accurate?"
but "has the reader yet been given a reason to want this?"
The most common single error is far too much background before any value has been shown.
Background can wait. Strong writers, in fact, rarely state background even later — they use
those moments to enrich the problem instead.
**Three shapes a problem can take.** Useful when diagnosing what a draft is actually claiming:
- **Gap** — the community does not know Y. Weakest by far. Works only when leaving Y unknown
demonstrably costs the readers something (see §6).
- **Error** — the community believes something that is wrong. Strongest, and the most
dangerous socially.
- **Instability** — the community holds views that do not fit together, or that fit the
evidence badly. Usually the most workable.
Note a practical consequence: **error problems are often dressed as gap problems for tact.** It
is more polite to tell readers they have a gap than that they are wrong, and junior authors
feel that pressure most. So when you are reading someone else's paper, do not assume "gap"
language means a gap — look at what is actually being claimed. And when the author's real
claim is error, help them decide how discreet they need to be, rather than letting the gap
phrasing hollow out a strong contribution.
## 8. Movement, not exposition
Readers experience good writing as motion. Bad academic writing sits still and accumulates:
another study summarized, another consideration noted, another qualification added.
**Symptoms of a stalled text:**
- Paragraphs that begin with "Additionally," "Furthermore," "Another," "It is also worth."
These announce accumulation, not development.
- Paragraph openings that all name the same topic — the text is circling.
- Long stretches with no contrastive markers — nothing is at risk.
- A literature review that is a sequence of "Smith (2019) found... Jones (2021) found..." with
no tension between the entries.
- The genuinely interesting claim appearing for the first time in the conclusion.
**The topic-string test.** Extract the first six words of every paragraph and read them in
sequence. That list should read like an argument advancing. If it reads like a table of
contents, the draft is organized by topic rather than by argument.
## 9. The code
Every scholarly community has a vocabulary that does two jobs: it names concepts precisely,
and it marks you as a member. Writing outside the code — using ordinary language for things
the field names specifically — signals that you are talking *about* the community rather than
*in* it, and readers discount accordingly.
**How to find a community's code (assign this to the author):** take three recent,
well-regarded articles from the exact venue they're targeting. Circle every word that appears
repeatedly and would look odd in a newspaper. That set is the code. Then check which of those
words appear in their draft, and in what proportion.
Two failure modes, and they need opposite fixes:
- **Under-coded.** Generic language where the field has a term; explaining concepts the
readers own; citing textbooks rather than the current conversation. Reads as outsider.
- **Jargon-as-costume.** Code words piled on with no work being done — abstraction covering
the absence of a claim. Reads as an insider with nothing to say. Test: delete the technical
terms and see whether a claim remains.
Code is not the same as difficulty. Using the field's terms precisely while keeping subjects
and verbs concrete is the target.
## 10. Clarity is not in the text
Writers treat clarity as a property of sentences. It isn't — it's an effect produced in a
reader whose expectations are being met. The same paragraph is crystalline to one community
and opaque to another. This has a practical consequence: **you cannot make writing clear by
staring at it.** You make it clear by modeling a specific reader's expectations and meeting
them. Level-5 sentence craft (see `sentence-patterns.md`) works precisely because those
patterns match how readers process English, not because they are aesthetically superior.
## 11. Two drafts, two audiences
The productive workflow separates the functions:
- **Draft 1, for you.** Write fast, badly, to find out what you think. Do not edit. Its job is
to end with you understanding your own claim.
- **Draft 2, for them.** Do not polish draft 1 — *rebuild* it. Start from: who reads this,
what do they currently believe, what instability threatens them, what does it cost them,
what do I want them believing at the end. The structure of draft 2 usually bears no
resemblance to draft 1.
Writers who skip this get stuck sanding a document whose architecture was designed for an
audience of one. When a draft shows function-1 signatures throughout, the recommendation is
not line edits — it's that they have finished draft 1 and haven't started draft 2 yet. Say
that plainly. It is usually a relief, not an insult.
## 12. Common objections
**"My field requires a background section."** Sometimes true. Check what recent papers in that
exact venue do. Where background is genuinely required, it can still be written as
destabilization rather than exposition — the background can build toward the anomaly instead
of surveying the terrain.
**"My advisor told me to be comprehensive."** Advisors are sometimes reading as evaluators
(function 2/school mode) rather than as the eventual audience. Both readers exist and the
author has to satisfy the near one. Name the tension honestly rather than pretending the
advisor is wrong.
**"This is a thesis/dissertation, and the committee IS paid to read it."** Correct — the
school contract genuinely still applies. But a dissertation that will become articles or a
book needs draft-2 architecture eventually, and building the habit now is cheaper than
retrofitting.
**"Isn't this all just marketing?"** No. The framework asks you to identify a real problem for
real readers and show real consequences. Manufacturing false stakes for a trivial finding is a
different failure, and a review should call it out just as fast as the absence of stakes.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |