Review and write academic prose
Table of Contents
1. Contract
- Implements
- citation. The skill states a standard cited at a point of judgement about prose. It runs nothing and sequences no work. See Regulatory Functions.
2. When to use this skill
Use this skill when writing or reviewing an org-roam document that makes an argument: knowledge, meta, investigation and design documents. It is the mandated style for that corpus.
Do not use it for an agent's replies to a person, which follow ASD-STE100, nor for skills, memories and specifications, which are written for agents to execute.
3. How to use this skill
Review in the order below and stop at the first layer that fails. Structure governs sentences and sentences govern words, so repairing a clause inside a paragraph that has no point is wasted work.
Report findings per layer. Do not rewrite the document unless asked; the author keeps the judgement.
3.1. 1. Claim
State the document's claim in one sentence, using only what the document says.
If you cannot, the document has no claim and every later layer is premature. A document that surveys without concluding is a reference, and belongs under a different standard.
3.2. 2. Spine
For each section, say in one clause which move it makes toward the claim. Swales' three moves name the usual sequence: establish the territory, establish the niche, occupy the niche.
- A section you can only describe as "it lists X" is not arguing.
- A section whose move duplicates its neighbour's should merge.
- A finding stated before the evidence that produces it is asserted, not derived. Move it after.
3.3. 3. Paragraph
State each paragraph's single idea. Two ideas means split it. No idea means cut it.
The first sentence carries that idea. A paragraph opening on meta-commentary about the document, rather than on its subject, has buried its point by one sentence.
3.4. 4. Sentence
Gopen and Swan's reader-expectation rules. Each has a mechanical test.
| Rule | Test |
|---|---|
| Topic position | Does the opening name what the sentence is about? |
| Stress position | Does the ending carry what the reader should remember? |
| Old before new | Does known material precede the new claim? |
| Subject and verb close | Count the words between them; over about seven, rewrite |
| Action in the verb | Find nominalisations and turn them back into verbs |
Two further rules earn their place in this corpus.
- Every referring expression resolves once. "The first", "the second", "it", "them", "this". Each must have exactly one antecedent a reader can find without counting back through a list. An ordinal referring to an unnamed list is the commonest failure here; name the thing instead.
- No chained pronouns. Two referring expressions in one sentence, each pointing at a different antecedent, is one too many.
3.5. 5. Term
List every term the document uses more than three times. For each, state its one referent.
- A term with two referents is either split into two terms, or the document says which is meant at each use.
- A term the corpus already owns keeps the corpus meaning. Check the glossary before coining.
- One name per thing, throughout. Rewording an unchanged idea teaches the reader a second thing that does not exist.
3.6. 6. Evidence
Every claim is derived from something stated, cited to a source, or labelled as unsupported. There is no fourth option.
- Verify each citation against the source before it lands. Author, year, venue and page.
- Attribute the argument to whoever made it, not to whoever is more famous.
- An aphorism is not a premise. "A definition admitting everything discriminates nothing" argues by maxim; state the criterion instead.
3.7. 7. Honesty
- State limits rather than leaving a reader to infer them.
- Claim no more than the evidence carries. Where a mechanism only advises, say it advises.
- State current or target state, never the difference from an earlier draft. A document does not narrate its own writing.
- An aside earns a note box only when it is genuinely tangential. A box explaining the document's relationship to another document is a symptom, not an aside.
4. Worked example
Before, from an early draft of The Cybernetic Skills Framework:
The classification is informative in one respect the surface descriptions conceal. The first and third failures constitute a single class. In both, the agent acts without a fact it required; they differ only in why the fact was absent, being available and unloaded in the one case and absent from training in the other. One remedy answers both, and the difference between them determines its form rather than its kind. The first requires an obligation to load what exists. The second requires that the construct be declared before there is anything to load.
After:
Two of those four descriptions are the same failure. An agent that asserts an unverified domain fact and an agent that cannot apply a convention we invented have both acted without a fact they needed.
They differ in why the fact was missing. The domain fact exists in a knowledge document and was not loaded. The convention could not have been known at all, because this project invented it.
That difference changes the form of the remedy and not its kind. Both require the fact to be supplied. The first requires an obligation to load what already exists. The second requires the convention to be written down before there is anything to load.
The failures, by layer.
- Paragraph. The first sentence is meta-commentary about the classification, so the point arrives one sentence late.
- Sentence, topic position. That sentence opens on "the classification" while the paragraph is about two failures being one.
- Sentence, stress position. It ends on "conceal", which the reader does not need to remember.
- Sentence, referring expressions. "The first and third failures" needs the reader to count back through an unnumbered list of four. The rewrite names them.
- Sentence, chained pronouns. "they differ", "them" and "its" chain across one sentence with different antecedents.
- Term. "Failures", "classes" and "descriptions" appear for overlapping things without the document saying whether they differ.
- Sentence, action in the verb. "Constitute a single class" is a nominalisation of "are the same failure".
5. Recipes
This skill indexes no recipes. It states a standard rather than a procedure over commands, so there is nothing operational to delegate.
6. Reference
- Zettelkasten — the structure of the corpus this skill governs.
- Glossary — the register of record for terms.
- compass-doc-review-ste100 — the standard for replies to a person.
- The pstack Collection —
technical-writingandunslop, which own product documentation and slop patterns respectively.
6.1. Sources
- Gopen, G. D. and Swan, J. A. (1990). The Science of Scientific Writing. American Scientist 78(6), 550-558. Supplies the sentence layer: topic position, stress position, old before new, subject and verb proximity, one idea per unit of discourse, and action carried by the verb.
- Swales, J. M. (1990). Genre Analysis: English in Academic and Research Settings. Cambridge University Press. Supplies the spine layer: the three moves of establishing a territory, establishing a niche, and occupying the niche, known as the CARS model.
- ASD-STE100 Simplified Technical English. Reached through compass-doc-review-ste100, which holds the rules and their scope.
The term, evidence and honesty layers are this project's own, derived from errors observed in this corpus rather than from a published standard.