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/argument-patterns.md
View on GitHub# Argument patterns and diagnostics
Reusable scaffolds for the value/problem/movement layers. Project-specific failure→repair
examples belong in `project/lexicon.md`, not here.
## Value-map template
Write six compact statements before drafting or restructuring anything.
```text
Readers: Who specifically needs this result?
Shared belief/capability: What do they already accept or already do?
Instability: What important relation is unresolved, contradictory, untestable?
Consequence of instability: What does that block — explanation, prediction, measurement,
accumulation across studies?
This study's response: What exactly does the work contribute?
Change for readers: What can they understand or test differently afterward?
Evidence boundary: What does the design not establish?
```
Reject generic formulations — "little is known," "no study has examined," "this topic is
important" — unless followed by a specific intellectual consequence. A gap is not a problem.
A problem is an instability in a community's understanding *with a cost*.
Then test the map against the design: **can this study actually deliver that value?** Narrow
the promise until claim and evidence match. Build the section sequence only after the value
claim survives that test.
## Introduction move sequence
1. Shared phenomenon, in the outer reader's terms.
2. Existing explanatory achievement — what the field can already account for.
3. The precise instability and its cost.
4. Candidate resolution and the linking proposition it depends on.
5. The design that can test that proposition.
6. Calibrated predictions or questions, with confirmatory/exploratory status stated.
## Discussion move sequence
1. Direct answer, sized to the evidence.
2. What changes theoretically or methodologically.
3. What the preferred interpretation does and does not rule out.
4. Four-validity boundary: construct, internal, statistical, external.
5. The specific next discriminating test.
6. The smallest important conclusion.
## Reverse outline before rewriting
For every paragraph, record:
| Paragraph | Function | Claim | Support | Reader transition | Keep/merge/split/delete |
|---|---|---|---|---|---|
Then act on it: merge paragraphs with duplicate functions, split paragraphs doing two
argumentative jobs, delete background that does not change the reader's route to the main
claim. A paragraph whose removal costs the argument nothing is not "context" — it is padding
that spends the reader's attention budget.
## Using the literature as a conversation
Organize prior work by its role in the instability, never as a list:
- what the community can already explain;
- where those explanations stop;
- competing interpretations;
- what evidence would discriminate between them or connect them.
Each source should change the logic of the problem. A citation that could be deleted without
altering the argument is decoration.
## Common failure → repair
- **Topic opening** — "X is ubiquitous." → Open with the operation or decision the study helps
explain.
- **Gap worship** — "No study has used method Y." → State what the field cannot currently
predict or test.
- **Theory parade** — one paragraph per theory. → Select one backbone; admit a second only for
a distinct link or a rival prediction.
- **Method-first value** — "We developed tool Z." → Name the inference that becomes possible,
then validate that inference.
- **Result inflation** — "X explains Y." → Name the specific measure, the association, its
uncertainty, and the surviving alternatives.
- **Limitation dump** — a generic final paragraph. → Tie each limitation to the exact
inference it weakens and the next test that would address it.
## Test value against evidence
Before endorsing a contribution sentence, ask:
- Does the study observe the proposed construct, or a proxy for it?
- Does the design distinguish the preferred explanation from simpler alternatives — exposure,
time, salience, volume, selection?
- Is the inference across participants, time, stimuli, or all three?
- Would the claim remain interesting if the focal coefficient were null?
- What is the smallest conclusion that still changes how an outer reader thinks?
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: 471k | 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 |