Skip to content

ShiyanW/ai-revision-guard

revision-guard

Verified

Use 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:

  1. The perfectionism trap. AI always finds something to "improve." Users iterate far past usefulness, ending up worse than their original draft.

  2. 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:

TypeScopeBoundary
StructuralReorder sections, adjust flow, reorganizeDon't rewrite sentences
SubstantiveStrengthen argument, add evidence, tighten logicDon't change voice; word changes are OK when needed to improve the argument
LanguageFix grammar, improve clarity, smooth transitionsDon't replace the author's natural expressions with academic clichés
FormattingFix LaTeX, citations, references, tablesDon't touch content
Full rewriteUser explicitly asked to rewrite from scratchSkip 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:

  1. 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.
  2. 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.
  3. 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:

PatternProblem
"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:

WordWhen it's OKWhen it's AI slop
"Notably" / "Importantly"Once per section as genuine signpostingEvery other paragraph
"The evidence suggests..."When the evidence genuinely only suggests, not confirmsReplacing "The data shows" for no reason
"Leverage"Technical meaning in finance/mechanicsReplacing "use"
"Demonstrate" / "Illustrate"When describing proofs, experiments, figuresReplacing "show" generically
"Utilize" / "Employ""Employ a method" is fine in methods sectionsReplacing "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:

RatingMeaningAction
SUBSTANTIALMaterially improved clarity, logic, or correctnessContinue if user wants
MINOR POLISHSmall grammar fixes, smoother transitionsSuggest finalizing
MARGINALLateral moves, not improvementsRecommend 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 Assessment FINALIZED; "Start fresh" (option 3 of the warning) appends one with RESET.
  • Next round (checked in Step 0): if the section's last row is a rewrite (R), FINALIZED, or RESET, 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.
RoundWhat happens
1Full revision → Report
2Follow-up on user's specific feedback → Report
3Warning (see below)

Round 3 warning:

"[N] rounds done on this section. More editing risks homogenization. Options:

  1. Finalize this version
  2. You edit the specific sentences you don't like
  3. 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

SettingDefaultHow to change
Max revision rounds2"Set max rounds to 3"
Domain presetInferred from the text, stated to the user"Use economics preset" / "Use law preset"
StrictnessStandard"Be stricter" / "Be more flexible"
Report verbosityFull"Skip the report" / "Brief report only"
Revision log.revision-log.md in the project root"Don't keep a log"
Cross-model checkOn when Codex is installed"Skip cross-check" / "Cross-check this"

User Commands

CommandEffect
"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:

FileWhen to load
references/research-evidence.mdUser asks why the skill exists, or you need citations
references/over-refinement-patterns.mdChecking a specific pattern or expanding the banned list
references/domain-presets.mdNeed full preset details for a field
scripts/diff-check.pyRun it (Step 5); no need to read it
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