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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.9 KB |
| examples/economics-revision-demo.md | markdown | 6.1 KB |
| references/domain-presets.md | markdown | 9.0 KB |
| references/over-refinement-patterns.md | markdown | 8.9 KB |
| references/research-evidence.md | markdown | 8.7 KB |
| scripts/diff-check.py | script | 17.7 KB |
examples/economics-revision-demo.md
View on GitHub# Example: Revising an Economics Paper Section
This walks through the revision-guard protocol on a Results section from a
difference-in-differences paper.
---
## Original text (user's draft)
> We find that the reform caused a 12.3% increase in college enrollment among
> affected cohorts (Column 3, Table 2). The effect is large — roughly equivalent
> to the enrollment gap between the top and bottom income quartiles in our
> baseline year. I argue this reflects genuine behavioral change rather than
> compositional shifts, because the enrollment increase persists when we restrict
> the sample to first-time enrollees.
>
> The parallel trends assumption holds. Figure 3 shows no differential
> pre-trends in the four years before the reform. The joint F-test on
> pre-treatment coefficients yields p = 0.47.
---
## Step 0: Anchor
**User says:** "Polish the language but don't change my argument."
One passage with a clear instruction, so the skill doesn't stop to ask. It
infers the field, applies the economics preset, and records the locks:
```
LOCKED: Results interpretation — "caused a 12.3% increase" (causal claim backed by identification strategy)
LOCKED: Contribution claim — "genuine behavioral change rather than compositional shifts"
LOCKED: Robustness assessment — "parallel trends assumption holds"
Domain preset: Economics (inferred from the text)
```
**Skill says:**
> "Keeping your causal claim, the 12.3% figure, and your parallel trends
> assessment as they are (economics preset). Say 'unlock' if you want those
> touched."
---
## Step 1: Classify
> "This is a **language** revision. I'll fix grammar and improve clarity but
> won't replace your word choices with academic clichés."
---
## Step 2: Execute (Round 1)
Claims first: each claim sits next to its evidence (Table 2, Figure 3, the
F-test), and every sentence earns its place. No defensive filler to cut. That
leaves sentence-level polish.
**Revised text:**
> We find that the reform caused a 12.3% increase in college enrollment among
> affected cohorts (Column 3, Table 2). This effect is large, roughly equivalent
> to the enrollment gap between the top and bottom income quartiles in our
> baseline year. I argue this reflects genuine behavioral change rather than
> compositional shifts, because the increase persists when we restrict the
> sample to first-time enrollees.
>
> The parallel trends assumption holds. Figure 3 shows no differential
> pre-trends in the four years before the reform, and the joint F-test on
> pre-treatment coefficients yields p = 0.47.
**Changes made:**
1. "The effect is large — roughly" → "This effect is large, roughly" (smoother connection)
2. "enrollment increase persists" → "increase persists" (removed redundant "enrollment")
3. Combined last two sentences with "and" (tighter)
---
## Step 5: Detect (runs before the report)
The before and after texts go through the diff checker:
```
$ python3 scripts/diff-check.py original.txt revised.txt
=== Revision Guard: Diff Check (edit mode) ===
[ok] Word count changed -1.1%
[ok] First-person pronouns: 4 → 4
[ok] Specific numbers: 2 → 2
[ok] Hedge words: 0 → 0 (0.0 → 0.0 per 100 words)
[ok] Sentence length spread (CV): 0.44 → 0.38
[ok] Sentences opening with stock transitions: 0 → 0
[ok] Paragraphs ending in a summary closer: 0 → 0
[ok] Verdict: CLEAN (0/7 checks flagged)
```
---
## Step 3: Report
```
Revision Report
───────────────
Section: Results, round 1
Changes: 3
Types: 0 structural / 0 substantive / 3 language / 0 formatting
Locked: none touched
Diff check: CLEAN (0/7)
Assessment: MINOR POLISH
```
> "Only minor polish. This is a good stopping point unless you have specific
> sentences you want changed."
---
## Step 4: Log
The skill creates `.revision-log.md` in the project root and tells the user
once:
```
| Date | Section | Round | Type | Trigger | Assessment |
|------------|---------|-------|----------|---------|--------------|
| 2026-10-29 | Results | 1 | language | user | MINOR POLISH |
```
If the user comes back next week and asks for two more rounds on Results, the
second of those hits the round-3 warning, even in a new session.
---
## What a BAD revision would look like (without revision-guard)
> Our analysis suggests that the reform **may have contributed to** what appears
> to be approximately a 12.3% increase in college enrollment among affected
> cohorts (Column 3, Table 2). **It is worth noting that** this effect is
> **relatively** large, **potentially** equivalent to the enrollment gap between
> income quartiles. **The evidence is broadly consistent with** genuine
> behavioral change rather than compositional shifts, **although alternative
> explanations cannot be entirely ruled out**.
>
> **Importantly**, the parallel trends assumption **appears to be** satisfied.
> Figure 3 **suggests** no differential pre-trends, and the joint F-test
> **yields a p-value of** 0.47, **which may indicate** that pre-treatment
> coefficients are not jointly significant.
The diff checker catches it:
```
$ python3 scripts/diff-check.py original.txt bad.txt
=== Revision Guard: Diff Check (edit mode) ===
[ok] Word count changed +9.7%
[!!] First-person pronouns: 4 → 1 — voice may be erased
[ok] Specific numbers: 2 → 2
[!!] Hedge words: 0 → 12 (0.0 → 11.8 per 100 words) — confidence may be eroded
[ok] Sentence length spread (CV): 0.44 → 0.32
[!!] Sentences opening with stock transitions: 0 → 1 — mechanical rhythm
[ok] Paragraphs ending in a summary closer: 0 → 0
[!!] Verdict: HOMOGENIZATION WARNING (3/7 checks flagged)
```
**What went wrong:**
- "caused" → "may have contributed to" — **causal language softened** (pattern 6.1)
- "I argue" → "The evidence is broadly consistent with" — **voice erased** (pattern 2.1)
- "holds" → "appears to be satisfied" — **confidence eroded** (pattern 1.1)
- Added "It is worth noting," "Importantly," "although alternative explanations
cannot be entirely ruled out" — **filler and false balance** (patterns 3.2, 1.2)
- Every direct claim wrapped in hedging — **the entire section became weaker
without any factual change**
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: 323k | 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: 323k | 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: 323k | Updated | Claude CodeCodex | Verified | Install |