revision-guard
VerifiedUse this skill whenever the user asks to revise, edit, polish, rewrite, improve, refine, clean up, tighten, smooth out, or review existing prose — especially academic papers, dissertations, thesis chapters, literature reviews, grant proposals, or journal submissions, including prose in LaTeX source. Also activate when the user asks "is this good enough?", "am I over-editing?", says "lock this paragraph", or is on their second or later revision of the same section. Do NOT activate when the user asks to write something from scratch, or to review code, scripts, or data files.
Revision Guard
LLM revisions cause two documented problems:
-
The perfectionism trap. AI always finds something to "improve." Users iterate far past usefulness, ending up worse than their original draft.
-
Homogenization. Each revision pulls language toward the model's statistical center. In controlled tests, LLM revisions pushed essays in a common semantic direction, replaced far more of the author's vocabulary than human revisers did, cut pronouns, and changed the meaning even when asked for grammar fixes only.
This skill enforces a protocol that limits revision rounds, preserves the author's voice, and detects when edits are making text worse.
For research citations, see references/research-evidence.md.
Scope
This skill applies to revising existing text, not writing from scratch. If the user asks "write me an introduction," do not activate. If the user asks "rewrite my introduction" or "clean up this paragraph," activate. Prose inside LaTeX source counts; code, Stata do-files, and data files do not.
Track revision rounds per logical section (Introduction, Methods, Results, etc.), not per paragraph. If the user pastes a single paragraph for editing, that paragraph is its own section.
Protocol: 6 Steps (0 through 5), plus optional 5b
Step 0: Anchor — Identify What to Protect
Before any revision, establish what is locked. How depends on the request.
Check the round count first. If the project has a .revision-log.md
(Step 4), read this section's last row before anything else. If this request
would pass the max, show the Step 4 warning instead of revising.
One passage with a clear instruction ("fix the grammar in this paragraph," "tighten this"): don't stop to ask. State the default locks in one line and proceed:
"Keeping your causal claims and numbers as they are (economics preset). Say 'unlock' if you want those touched."
Several sections, or a vague request ("make my chapter better"): ask first:
"What parts are you happy with? I'll lock those and only edit what you want changed."
If the user says "everything is open": Do not infer or force-lock anything. Respect the instruction. The user may need a major rewrite — perhaps an advisor demanded it. Proceed with full revision permission.
If the user says "lock [specific thing]": Record locks explicitly:
LOCKED: [section/paragraph ID] — [user stated reason or "user request"]
Domain presets suggest default locks; the user can override any of them.
When the field is obvious from the text, apply its preset from
references/domain-presets.md and say which one you used. Ask only when the
field is unclear.
Locked content and factual errors: Locking protects voice and argument framing, not factual accuracy. If you notice a locked section contains a likely factual error (wrong number, incorrect citation, implausible claim), flag it:
"This section is locked, but I noticed [specific issue]. Want me to fix it, or is it intentional?"
Never silently preserve an error just because the section is locked.
Step 1: Classify — What Type of Edit?
Before editing, classify the request and state it:
| Type | Scope | Boundary |
|---|---|---|
| Structural | Reorder sections, adjust flow, reorganize | Don't rewrite sentences |
| Substantive | Strengthen argument, add evidence, tighten logic | Don't change voice; word changes are OK when needed to improve the argument |
| Language | Fix grammar, improve clarity, smooth transitions | Don't replace the author's natural expressions with academic clichés |
| Formatting | Fix LaTeX, citations, references, tables | Don't touch content |
| Full rewrite | User explicitly asked to rewrite from scratch | Skip minimal-change constraint; still run homogenization check at the end |
Say:
"This is a [TYPE] revision. I'll [scope] but won't [boundary]."
If the user explicitly asks for a full rewrite ("completely rewrite this," "I hate this section, start over"), classify as full rewrite. The minimal-change constraint and revision cap do not apply. The user has signaled they want a fresh take. Still run the homogenization check (Step 5, rewrite mode) on the output.
Step 2: Execute — Minimal Effective Change
Order of work. Whatever the edit type, read the text in this order:
- Claims. Does each claim match its evidence, and does each paragraph need to exist? Report problems to the user; change claims only in a substantive revision or a full rewrite.
- Defensive filler. Disclaimers and pre-emptive hedges that answer objections nobody raised ("We do not claim that...", "While this study has limitations..."). In a substantive revision or a full rewrite, cut them unless they mark a real scope limit or sit in locked text. In any other edit type, list them for the user instead of cutting: the Step 1 boundary and the Step 0 locks win.
- Sentences. Only now polish wording.
Polishing a sentence that should be deleted wastes a round.
Make the fewest changes that accomplish the stated goal. For each change, ask: "Would a careful human editor make this change, or am I making it because I can?"
Preserve:
- Sentence length variety (don't normalize to uniform length)
- Specificity (don't replace concrete examples with abstractions)
- Confidence level (don't add hedging the author didn't include)
- First-person voice (don't convert "I find" to "It is observed")
Banned substitutions — do not introduce these unless the user explicitly asks for them:
| Pattern | Problem |
|---|---|
| "It is worth noting that..." | Filler |
| "This is not merely X, but also Y..." | Inflated parallelism |
| "In the rapidly evolving landscape of..." | Empty preamble |
| "A comprehensive analysis reveals..." | Vague authority claim |
| "It is important to emphasize that..." | Tells reader what to think |
| "This represents a paradigm shift..." | Hyperbole |
| "The findings underscore..." | Generic verb replacing a specific one |
| "This speaks to the broader question of..." | Vague pivot |
| "It is observed that..." replacing "I find..." | De-personalization |
| "A nuanced understanding..." | Empty modifier |
| "In light of the foregoing..." | Legalistic filler |
| "This is consistent with the notion that..." | Wordy agreement |
Context-dependent words — these are fine in moderation but flag overuse:
| Word | When it's OK | When it's AI slop |
|---|---|---|
| "Notably" / "Importantly" | Once per section as genuine signposting | Every other paragraph |
| "The evidence suggests..." | When the evidence genuinely only suggests, not confirms | Replacing "The data shows" for no reason |
| "Leverage" | Technical meaning in finance/mechanics | Replacing "use" |
| "Demonstrate" / "Illustrate" | When describing proofs, experiments, figures | Replacing "show" generically |
| "Utilize" / "Employ" | "Employ a method" is fine in methods sections | Replacing "use" everywhere |
Word lists catch only the surface. The stronger tell is structure: every paragraph ending on a sentence that explains its own point back to the reader ("This suggests that..."), every sentence the same length, every other sentence opening with "Moreover." Don't introduce those either.
For the full pattern catalog, see references/over-refinement-patterns.md.
Step 3: Report — Self-Assessment
After completing a revision, run Step 5, then produce a brief report:
Revision Report
───────────────
Section: [name], round [N]
Changes: [number]
Types: [X structural / Y substantive / Z language / W formatting]
Locked: [none touched / list which and why]
Diff check: [CLEAN / MINOR CONCERNS / HOMOGENIZATION WARNING (k/N) / not run]
Assessment: [SUBSTANTIAL / MINOR POLISH / MARGINAL]
Copy k/N from the script's verdict line (7 checks in edit mode, 6 in substantive and rewrite modes).
Assessment criteria:
| Rating | Meaning | Action |
|---|---|---|
| SUBSTANTIAL | Materially improved clarity, logic, or correctness | Continue if user wants |
| MINOR POLISH | Small grammar fixes, smoother transitions | Suggest finalizing |
| MARGINAL | Lateral moves, not improvements | Recommend stopping |
Important caveat: This self-assessment is a rough signal, not gospel. The
research shows LLM self-correction is unreliable without external feedback
(see references/research-evidence.md, section 6). The diff check and the
cross-model check (Step 5b) are that external feedback. The report helps the
user decide, but the user makes the call. If the user disagrees with the
assessment, the user is right.
If MARGINAL:
"This revision is marginal — I'm polishing, not improving. I'd suggest finalizing. Want to move on?"
If MINOR POLISH on round 2+:
"Only minor polish left. Good stopping point unless you have specific sentences you want changed."
If user says "skip the report" or "brief report only": Respect it. Give a one-line assessment or skip entirely.
Step 4: Limit — The Revision Cap
Count rounds in a file, not from memory. Conversations run long, and a new session remembers nothing about earlier rounds.
The log. Keep .revision-log.md in the project root (the directory that
holds the user's draft). Create it on the first revision and tell the user
once. Append one row per round:
| Date | Section | Round | Type | Trigger | Assessment |
|------------|--------------|-------|-------------|----------|--------------|
| 2026-10-29 | Introduction | 1 | language | user | MINOR POLISH |
| 2026-10-29 | Introduction | 2 | language | user | MARGINAL |
| 2026-11-03 | Introduction | 1 | substantive | reviewer | SUBSTANTIAL |
- Round counts consecutive user-initiated rounds on a section. A round driven by new reviewer or advisor comments restarts the count at 1 and records the trigger: that is new input, not aimless polishing.
- Full rewrites are logged with Round
R. They don't count toward the cap, and the next round on the rewritten text starts at 1. - "Finalize" appends a row with Round
-and AssessmentFINALIZED; "Start fresh" (option 3 of the warning) appends one withRESET. - Next round (checked in Step 0): if the section's last row is a rewrite
(
R),FINALIZED, orRESET, the next round is 1; otherwise it is that row's Round + 1. If the next round would pass the max, show the warning instead of revising. - No file system (a chat-only agent), or the user says "don't keep a log": count rounds in the conversation. If the user says "I already revised this twice in a previous session," start the counter at their number.
| Round | What happens |
|---|---|
| 1 | Full revision → Report |
| 2 | Follow-up on user's specific feedback → Report |
| 3 | Warning (see below) |
Round 3 warning:
"[N] rounds done on this section. More editing risks homogenization. Options:
- Finalize this version
- You edit the specific sentences you don't like
- Start fresh in a new conversation with clear constraints (I'll log a reset, so the count starts over)
Say 'continue anyway' to override."
The user can override; log the round as usual.
If the user sets a different max ("set max rounds to 3"), write it as the
first line of the log (Max rounds: 3) so later sessions use it. The warning
shifts to round N+1. The cap is a default, not a hard wall.
Step 5: Detect — Homogenization Check
After each revision, compare the new text against the pre-revision version.
Run the diff checker when you can execute Python. Write the pre-revision
and revised text to two temporary files (keep a .tex extension for LaTeX
source) and run, from this skill's directory:
python3 scripts/diff-check.py before.txt after.txt # language, structural, formatting
python3 scripts/diff-check.py --mode substantive before.txt after.txt # substantive
python3 scripts/diff-check.py --mode rewrite before.txt after.txt # full rewrite
Report its verdict in the revision report. The script counts; it doesn't read meaning. A changed claim or a lost example is yours to catch with the checklist below.
Checklist (always; the only check when the script can't run):
- Replaced 3+ of the user's word choices with "safer" alternatives?
- Text became more hedged or qualified?
- Specific examples or numbers replaced with generalizations?
- Tone shifted from confident to cautious?
- Sentence length variety decreased?
- First-person voice replaced with impersonal constructions?
- Domain-specific terms replaced with generic academic language?
For a full rewrite, every word changes by design, so ask these of the new text itself: Is it hedged? Is the author's "I/we" gone? Did numbers disappear? Do the paragraphs all end on a summary sentence?
If the script warns, or 2+ checklist items are YES:
"Homogenization warning: this revision made your text more generic. Specifically: [list what changed]. Want me to revert those changes?"
Step 5b (Optional): Cross-Model Verification
Self-assessment (Step 3) and the checklist (Step 5) both rely on the same model that made the revision. A model that over-refined text may not recognize it did so. A second, independent model removes this blind spot.
When Codex is available (codex:rescue exists in this session), run the
cross-check by default for:
- Substantive and full-rewrite revisions
- Round 2+ of any revision
- High-stakes text: results interpretation, identification strategy, contribution statements
Start it in parallel with Step 5 (it only needs the before/after text) and merge its findings into the report. Skip it for formatting-only edits, or when the user says "skip cross-check."
Send to Codex with codex:rescue:
Compare these two versions of an academic text section.
The first is the author's version, the second is my revision.
Check: (1) Did the revision weaken any claims without justification?
(2) Did it replace specific language with generic alternatives?
(3) Did it shift tone from confident to hedged?
(4) Did it remove the author's voice?
Report only problems found. If the revision is clean, say so.
ORIGINAL:
[paste original]
REVISED:
[paste revised]
If Codex is not installed: Skip this step silently. Do not error or nag. Mention in the revision report:
"Tip: Install Codex (
/codex:setup) to enable cross-model verification — a second AI independently checks whether my revision degraded your text."
This message appears once per session, not every round.
If the user's agent tool supports other external models (e.g., Gemini CLI, OpenRouter), the same pattern applies — send the before/after to any independent model for comparison.
Domain Presets
Presets for economics, law, medicine, humanities, STEM, psychology, political
science, and education are in references/domain-presets.md. Each locks four
to five section types to grammar-only edits; economics, for example, locks
results interpretation, identification strategy, contribution claims,
robustness assessments, and policy implications.
Presets are defaults. Users override any lock by saying "unlock [section]." For fields not listed (sociology, business, public health, etc.), ask the user which sections they consider core arguments, and lock those.
Configuration
| Setting | Default | How to change |
|---|---|---|
| Max revision rounds | 2 | "Set max rounds to 3" |
| Domain preset | Inferred from the text, stated to the user | "Use economics preset" / "Use law preset" |
| Strictness | Standard | "Be stricter" / "Be more flexible" |
| Report verbosity | Full | "Skip the report" / "Brief report only" |
| Revision log | .revision-log.md in the project root | "Don't keep a log" |
| Cross-model check | On when Codex is installed | "Skip cross-check" / "Cross-check this" |
User Commands
| Command | Effect |
|---|---|
| "Lock this paragraph" | Preserve meaning and tone in future revisions |
| "Unlock everything" | Full revision permission — no forced locks |
| "Is this good enough?" | Honest assessment: finalize or keep editing |
| "Am I over-editing?" | Read the log for round counts + run the homogenization check |
| "Revert last round" | Undo most recent revision |
| "Finalize" | Mark the section done in the log |
| "Use [domain] preset" | Switch to field-specific default locks |
| "Continue anyway" | Override the revision cap warning |
| "Cross-check this" / "Skip cross-check" | Turn the second-model review on or off for this revision |
Reference Files
Loaded on demand, not all at once:
| File | When to load |
|---|---|
references/research-evidence.md | User asks why the skill exists, or you need citations |
references/over-refinement-patterns.md | Checking a specific pattern or expanding the banned list |
references/domain-presets.md | Need full preset details for a field |
scripts/diff-check.py | Run it (Step 5); no need to read it |
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 |