How-to guide

How to run a prose review on a document

Problem: You have a document and want it clearer and easier to read, but you do not know which controls to reach for—or you want the agent to calibrate to your goals before it touches a word.

Use when: Any draft worth improving—specs, docs, essays, emails, narrative.

How it works

Two prompts, two stages. Copy Stage 1 into a session and attach your document. The agent reads it, interviews you about your goals, then hands back a calibrated menu of prose controls. Reply with the numbers you want, paste Stage 2, and it applies exactly those edits—written to run unattended inside a /goal or long-running session.

Steps

Open a fresh session and attach (or paste) the document you want reviewed.
Copy Stage 1 below and send it. Answer the interview questions.
Read the recommendation menu. Note the numbers you want to apply.
Copy Stage 2, fill in your selected controls and the document path, and send it.
Review the changelog it returns; iterate on any items it flagged.

Stage 1 · Analyze & Recommend

The agent reads, interviews, and recommends. It does not edit yet.

Copyable Prompt · Stage 1

You are a prose editor working from a fixed catalogue of "prose controls" (named, well-defined editing techniques). Your job in this stage is to READ, INTERVIEW, and RECOMMEND. Do NOT edit the document yet.

INPUT: I will provide a document (path or pasted text). If none is attached, ask for it before doing anything else.

Follow these steps in order.

STEP 1 — Read and profile (silent analysis, then a short report).
Read the entire document. Then give me a compact profile:
- What the document appears to be (type, e.g. spec / how-to / essay / email / narrative).
- Its apparent audience and purpose, as YOU infer them from the text alone.
- 3–6 concrete prose problems you observe, each with a one-line quote or location.
Keep this under ~200 words. Do not recommend fixes yet.

STEP 2 — Interview me to calibrate.
Ask me a SHORT batch of questions (5–8 max) whose answers would change your recommendations. Cover at least:
- Primary goal of the document and the single action/understanding I want from a reader.
- Who the reader is, their expertise, and how much time/attention they have.
- Target reading time or length constraint, if any.
- Register/voice desired (and any that are off-limits).
- Whether this is normative (requirements/spec) or descriptive/persuasive.
- What must NOT change (fixed terminology, facts, structure, legal wording).
- Where the document will live and how it will be maintained (diffs, translation, etc.).
Ask everything in one message, numbered. Then STOP and wait for my answers.

STEP 3 — Recommend a calibrated menu.
Using my answers, select the SMALLEST set of controls that will most improve clarity and readability. Prefer high-leverage changes; avoid piling on techniques that fight each other. Present the menu as a numbered table:

# | Control | Why it helps THIS document | Scope | Effort/Risk
---|---------|----------------------------|-------|------------

- "Why" must reference a specific problem from Step 1 or a goal from Step 2.
- "Scope" = whole document / specific sections / specific sentences (name them).
- "Effort/Risk" = a quick low/med/high on how invasive the change is.
Order the menu by impact. Mark 2–4 items as "Recommended first pass".
After the table, note any tensions or trade-offs (e.g. "shorter reading time conflicts with the requested formal register").

Finally, tell me to reply with the numbers I want and to paste "Stage 2".

CATALOGUE OF CONTROLS you may draw from (use these names exactly):

Sentence Architecture & Syntax
- Parataxis vs. Hypotaxis — coordinate short clauses vs. subordinate for pace/logic.
- Periodic Sentences — delay the main point to the end for tension.
- Isocolon / Tricolon — parallel structure and three-beat rhythm.

Narrative Distance & Point of View
- Psychic Distance — set how close the reader stands to a mind (a dial 1–5).
- Free Indirect Discourse — blend narrator and character voice.
- Internal Focalization — filter everything through one perspective.

Lexical Mechanics & Style
- De-nominalization — turn noun-heavy phrases back into verbs.
- Lexical Density — tune content-word ratio (heavier = denser, harder).
- Micro-Register — name an exact linguistic mode (clinical, consultative, etc.).

Structural & Systemic Constraints
- E-Prime — remove all forms of "to be" to force concrete claims.
- Readability Metrics — target a Flesch–Kincaid grade / sentence length.

Length, Reading Speed & Audience Comprehension
- Reading Time & Word-Count Calibration — back a word budget out of a target minutes-to-read.

Controlled Natural Languages & Constrained Registers
- Simplified Technical English (ASD-STE100) — restricted grammar + approved verbs.
- Basic English & Restricted Lexicons — cap vocabulary to a core word list.
- Attempto Controlled English (ACE) — unambiguous, machine-parseable subset.
- RFC-2119 Normative Keywords — MUST/SHOULD/MAY for requirements.
- Structured Topic Typing (DITA) — concept/task/reference typing.

Cognitive Load & Information Design
- Given–New Information Structure — open each sentence with known info, end with new.
- Cohesion & Topic Chaining — keep a consistent subject thread across sentences.
- Bottom Line Up Front (BLUF) — lead with the conclusion.
- Progressive Disclosure — reveal detail in layers.
- Chunking & List Discipline — group and cap items; convert prose to lists where apt.
- Signposting & Metadiscourse — add headings, transitions, "in this section" cues.

Precision & Disambiguation
- Controlled Vocabulary — one term per concept, no elegant variation.
- Anaphora & Reference Resolution — kill dangling "it/this/they".
- Quantifier & Scope Precision — pin down "all/some/each/only".
- Hedging vs. Commitment — calibrate certainty; remove accidental hedges.
- Negation Reduction — state things positively where possible.
- Verb Tense Consistency — enforce temporal harmony and eliminate accidental tense shifts.

Technical Communication Formats
- Semantic Line Breaks — one clause per line for clean diffs/translation.
- Inverted Pyramid — most newsworthy first, background last.
- Minimalist Instruction — cut everything not needed to complete the task.
- Procedural Imperative Voice — steps as direct commands ("Click Save").

Begin at STEP 1 now.

Stage 2 · Apply selected controls

Paste this after you reply with your chosen numbers. Fill in the two <…> placeholders first.

Copyable Prompt · Stage 2

GOAL: Apply the prose controls I selected to the document, in place, producing a clean, production-ready deliverable.

SELECTED CONTROLS: <list the numbers/names you chose from the Stage 1 menu>
DOCUMENT: <path, or "the document from Stage 1">

Operating rules for this session:
1. Work from the Stage 1 profile, my interview answers, and the selected menu items only. Do not introduce controls I did not select.
2. Respect every constraint I named as "must not change" (terminology, facts, structure, legal/normative wording).
3. Apply the controls in a sensible order: structural/reordering controls first (BLUF, Inverted Pyramid, Chunking, Signposting), then sentence-level controls (Given–New, De-nominalization, Anaphora, Quantifier Scope, Verb Tense Consistency), then register and line-level controls (Micro-Register, Semantic Line Breaks) last.
4. Make the edits directly to the file. If reading time or a readability grade was a target, check the result against it and adjust until it lands.
5. Preserve meaning. If any edit would change meaning or requires a decision I have not authorized, STOP and ask rather than guess.

Deliverable:
- The revised document, edited in place. Output ONLY the revised document text in the file itself — no revision notes, changelogs, or meta-commentary embedded in the file.
- In your chat response (NOT in the file), give me a brief changelog: which control you applied, where, and one example before/after per control. Note any place you stopped or made a judgment call.

Definition of done:
- Every selected control is applied or explicitly flagged as skipped-with-reason.
- Any numeric target (reading time, FK grade, word cap) is met and reported.
- The file contains only clean final prose.

Begin.