Skip to content

angushushu/shu-academic-writing-skill / core/engineer-argument

engineer-argument

Verified

Diagnose 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.

FileKindSize
SKILL.mdskill md12.8 KB
references/argument-patterns.mdmarkdown4.2 KB
references/diagnostics.mdmarkdown10.6 KB
references/drills.mdmarkdown6.1 KB
references/genres.mdmarkdown9.2 KB
references/principles.mdmarkdown16.2 KB
references/sentence-patterns.mdmarkdown5.1 KB

references/genres.md

View on GitHub
# Genre and Discipline Notes

The framework is constant; its surface expression is not. Read the relevant section before
reviewing, and when a convention is uncertain, ask the author what their target venue does
rather than importing generic advice.

## Contents

- [Document types](#document-types): [abstract](#abstract) · [introduction](#introduction) ·
  [literature review](#literature-review) · [methods](#methods) ·
  [results](#results) · [discussion](#discussion-and-conclusion) ·
  [grant proposal](#grant-or-research-proposal) · [dissertation chapter](#dissertation-chapter)
  · [cover letter](#journal-cover-letter) · [personal statement](#personal-or-research-statement)
  · [white paper](#policy-brief-or-white-paper) · [referee report](#referee-report)
- [Disciplinary variation](#disciplinary-variation)
- [Non-native English writers](#non-native-english-writers)

---

## Document types

### Abstract

The highest-leverage 200 words in academic writing — for most readers it is the entire paper.

Diagnose against: does it contain the instability, the cost, and the claim, or is it a
procedural summary ("This paper examines X using Y. Results are discussed.")? A results-free
abstract that promises discussion is the most common failure, and it costs more readers than
anything else in the document.

Structural test: an abstract should survive being read alone. If a reader can't tell what is
now true that wasn't before, it fails, regardless of how accurately it describes the paper.

### Introduction

Where the four-part engine lives. Audit hard: how many paragraphs before something is at risk?
How much of paragraph 1 is consensus? Is the claim stated, or promised for later?

Common structure failure: the funnel (general → narrow), which is a school habit. Its
replacement isn't a formula but a sequence — what they believe, what breaks it, what that
costs, what you claim.

Length norm varies enormously (a *Nature* intro is three paragraphs; a history article's may
run six pages). Ask the venue before flagging length.

### Literature review

The genre most prone to accumulation. The test: is it organized by *scholar* or by *problem*?
"Smith found... Jones found... Lee found..." is an annotated bibliography. A review earns its
place by building tension — showing that the accumulated work implies something inconsistent,
or leaves a load-bearing assumption unexamined.

Assign the reframe question: "What do these studies, taken together, commit your field to
believing — and where does that commitment fail?"

In a standalone review article, the value proposition is different: the contribution is the
organizing scheme itself. Diagnose whether there *is* one, or whether it's a list with
headings.

### Methods

Different rules apply and reviewers regularly get this wrong. Methods sections are read for
reproducibility and evaluation, often non-linearly, often by someone checking one detail.

- Instability markers are *not* expected. Do not flag their absence.
- Passive voice is often idiomatic and appropriate.
- Completeness genuinely matters here — this is the one place where "cover everything" is
  right.
- Still apply: characters/actions where agency matters, and ordering that matches how a
  replicator would work.

Focus review on findability: can a reader locate the one parameter they came for?

### Results

Diagnose the difference between *reporting* and *saying what happened*. A results section that
narrates every table in order is a data tour. Readers need to know which numbers carry the
claim.

Check: does each paragraph open with a finding, or with a reference to a table? "Table 3 shows
the distribution of..." spends the reader's attention on furniture. Check also whether the
non-results — the things that didn't work — are given proportionate space; overweighting them
is common and usually driven by the school habit of showing all the work.

### Discussion and conclusion

Where the buried treasure usually is. If the draft's most interesting claim first appears
here, that's a headline structural finding: the paper is written in discovery order.

Check for: the "limitations" section that undoes the claim rather than bounding it; the
final paragraph that gestures at "future research" instead of stating what is now true; and
whether the stakes named in the intro are actually paid off.

### Grant or research proposal

The cost step is not optional here — reviewers are explicitly allocating resources and must be
able to say what the field loses if this isn't funded. Diagnose:

- Is the problem framed as *the field's* problem or *the applicant's* interest?
- Does significance appear as assertion ("this is an important area") or as consequence?
- Is feasibility evidence present? Proposals fail on credibility as often as on value.
- Does it match the funder's stated criteria in the funder's own words? This is the code
  audit, applied to an agency instead of a journal.

### Dissertation chapter

Dual audience, and the tension is real: the committee *is* paid to read, and does sometimes
want the comprehensive display. Name the tension honestly rather than pretending only one
audience exists.

Useful frame: which parts of this chapter exist for the committee, and which would survive
into an article? Getting the author to sort their own draft into those two piles is often the
single most useful thing a review of a chapter can do.

### Journal cover letter

Short, and almost always written as a summary when it should be written as a case. The editor
is deciding whether to spend reviewers on it. Diagnose whether it states what the paper
changes for *this journal's* readership, or merely describes contents.

### Personal or research statement

Value still governs, but the community is a hiring or admissions committee and the change is
about *you*. The failure mode is chronology ("I first became interested in..."). Diagnose
whether the statement gives the committee a reason to believe this person will produce work
their department needs — and whether the arc is an argument or a résumé in sentences.

Be careful here: these documents carry real personal stakes. Keep the diagnosis just as
candid, but be attentive to how it lands.

### Policy brief or white paper

The reader is time-poor and decision-oriented. Front-load the recommendation; the reasoning
follows. Academic hedging that reads as rigor to a journal reads as evasion to a decision
maker. Diagnose whether the document tells the reader what to *do*, and whether the stakes are
in the reader's currency (cost, risk, timeline) rather than the researcher's.

### Referee report

If the author is writing a review of someone else's work, the same value logic applies
inverted: the report's reader is an editor deciding, plus an author revising. Diagnose whether
the report leads with the consequential judgment or buries it under line notes — and note
that a good referee report follows this skill's own rule: diagnosis over rewriting.

## Disciplinary variation

Hold these loosely; venue trumps discipline.

**Experimental sciences.** Short intros, high code density, claims tightly bounded by
evidence. Instability is often framed as a mechanistic gap. Passive is idiomatic in methods.
Overclaiming is punished hard.

**Quantitative social sciences.** Identification and inference are the code. Instability is
frequently "the accepted estimate is biased because." Robustness discussion is where
credibility is won or lost.

**Humanities.** Longer arcs, more tolerance for delayed claims, and prose texture is itself
part of the argument. Do *not* import science-paper compression here. But the engine still
runs: the field's best work almost always destabilizes an accepted reading. "Nobody has
examined this text" is as weak here as anywhere.

**Law.** Problem-first is native. Watch for the treatise habit — comprehensive doctrinal survey
before the claim.

**Engineering / CS.** Contribution lists are conventional and fine. Diagnose whether the
contributions are stated as capabilities delivered to a reader ("we show X is possible at Y
cost") or as work performed ("we implemented a system").

**Medicine / public health.** Structured formats constrain everything; the leverage is in the
significance statement and the framing of clinical consequence.

**Interdisciplinary work.** The hardest case, because there are two codes and two sets of
prior beliefs. The common failure is writing to a hybrid reader who doesn't exist. Push the
author to name the *primary* community and write to them, treating the second field as
resource rather than audience.

## Non-native English writers

Distinguish carefully, because conflating these does real damage:

- **Surface features** — article use, preposition choice, idiom — are usually the author's own
  concern and rarely why a paper gets rejected. Note them briefly, in one grouped comment, and
  move on.
- **Structural moves** — instability, cost, code — are what determine reception, and are
  learnable independent of fluency.

Some rhetorical traditions favor an indirect, context-first arc; a writer following that
convention isn't making an error, but Anglophone venues read it as a slow start. Say that as a
convention difference rather than a deficiency, and be explicit that the ideas are not the
problem.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall