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.

scripts/diff-check.py

View on GitHub
#!/usr/bin/env python3
"""
diff-check.py — Post-revision quality checker for revision-guard.

Compares original text against revised text and flags homogenization signals.
Usage:
    python scripts/diff-check.py original.txt revised.txt
    python scripts/diff-check.py --mode substantive original.txt revised.txt
    python scripts/diff-check.py --mode rewrite original.txt revised.txt
    python scripts/diff-check.py --text "original" "revised"
    python scripts/diff-check.py --json original.tex revised.tex

Modes (match the edit type from SKILL.md Step 1):
    edit (default)  Language, structural, and formatting edits.
    substantive     Substantive edits: added material is expected, so word
                    count growth is reported but not flagged.
    rewrite         Full rewrites, where nearly every word changes by design.
                    Flags the revised text only where it is both weak in
                    absolute terms and worse than the original.

Checks:
    1. Word count growth (>15% = likely filler; edit mode only)
    2. First-person pronouns (dropped to zero, or down by 2+ and 25%+)
    3. Specific numbers (a number from the original is missing = generalization)
    4. Hedges (2+ more, at a higher density per 100 words)
    5. Sentence length spread (much more uniform, and uniform in absolute terms)
    6. Stock transitions ("Moreover," "Furthermore," ... opening sentences)
    7. Summary closers ("This suggests..." ending a paragraph)

Two or more flags = homogenization warning. Files ending in .tex have LaTeX
comments and \\cite/\\ref commands removed before analysis.
"""

import sys
import re
import json
import argparse
import statistics
from decimal import Decimal, InvalidOperation
from pathlib import Path


# --- Text preparation -------------------------------------------------------

# Abbreviations that never end a sentence, and ones that sometimes do.
ABBREVIATIONS = (
    'e.g.', 'i.e.', 'cf.', 'vs.', 'approx.', 's.e.', 'S.E.', 'Fig.', 'Figs.',
    'Eq.', 'Eqs.', 'Tab.', 'Sec.', 'Ch.', 'App.', 'No.', 'pp.', 'Dr.', 'Mr.',
    'Ms.', 'Mrs.', 'Prof.', 'Jan.', 'Feb.', 'Aug.', 'Sept.', 'Oct.', 'Nov.', 'Dec.',
)
SENTENCE_END_ABBREVIATIONS = ('et al.', 'etc.', 'resp.', 'U.S.', 'U.K.', 'Inc.', 'Ltd.', 'Co.')
SENTENCE_STARTER = re.compile(
    r'^["\'\u201c\u2018(]?(?:The|This|These|That|Those|There|Here|It|We|I|Our|My|'
    r'In|On|At|For|From|With|By|As|A|An|But|And|Yet|So|Thus|Hence|However|'
    r'Moreover|Furthermore|Additionally|Overall|Such|Taken|Together|Finally|'
    r'First|Second|Third|Notably|Importantly|Indeed|Instead|Because|Since|'
    r'When|While|If|Although|Using)\b'
)
# A capital letter after these is a label ("Panel A."), not a person's initial.
LETTER_LABELS = {
    'Panel', 'Appendix', 'Table', 'Figure', 'Column', 'Section', 'Part', 'Model',
    'Plan', 'Exhibit', 'Group', 'Sample', 'Period', 'Region', 'Scenario', 'Option',
    'Treatment', 'Arm', 'Case', 'Type', 'Class', 'Tier', 'Study', 'Wave', 'Phase',
    'Stage', 'Step', 'Hypothesis', 'Specification', 'Grade',
}

SENTENCE_BOUNDARY = re.compile(
    r'(?<=[.!?])["\'\u201d\u2019)\]]*\s+(?=["\'\u201c\u2018(\[]?[A-Z0-9$\\])'
)


def strip_latex(text: str) -> str:
    # % starts a comment unless escaped by an odd number of backslashes
    text = re.sub(r'(?m)(^|[^\\])((?:\\\\)*)%.*$', r'\1\2', text)
    text = re.sub(r'\\(?:[a-zA-Z]*cite[a-zA-Z]*|[cC]?ref|eqref|autoref|pageref|label)\*?'
                  r'(?:\[[^\]]*\])*\{[^}]*\}', '', text)
    return text.replace('\\%', '%').replace('~', ' ')


def paragraphs(text: str) -> list:
    blocks = re.split(r'\n\s*\n', text)
    return [re.sub(r'\s+', ' ', b).strip() for b in blocks if b.strip()]


def ends_with(sentence: str, abbreviations) -> bool:
    s = sentence.rstrip()
    return any(s.endswith(a) and (len(s) == len(a) or not s[-len(a) - 1].isalpha())
               for a in abbreviations)


def continues_sentence(previous: str, following: str) -> bool:
    """True if a split after `previous` fell on an abbreviation, not a sentence end."""
    previous = previous.rstrip()
    if re.fullmatch(r'\(?\d{1,2}[.)]', previous):  # list marker: "1."
        return True
    if ends_with(previous, ABBREVIATIONS):
        return True
    initial = re.search(r'(?:^|\s)(?:(\w+)\s+)?[A-Z]\.$', previous)  # "Joel Z. Leibo"
    if initial and initial.group(1) in LETTER_LABELS:
        return False  # "Panel A."
    if initial or ends_with(previous, SENTENCE_END_ABBREVIATIONS):
        return not SENTENCE_STARTER.match(following)
    return False


def split_sentences(paragraph: str) -> list:
    sentences = []
    for part in SENTENCE_BOUNDARY.split(paragraph.strip()):
        if sentences and continues_sentence(sentences[-1], part):
            sentences[-1] += ' ' + part
        else:
            sentences.append(part)
    return [s for s in sentences if s.strip()]


def all_sentences(text: str) -> list:
    return [s for p in paragraphs(text) for s in split_sentences(p)]


def count_words(text: str) -> int:
    return len(text.split())


# --- Signals ----------------------------------------------------------------

FIRST_PERSON = re.compile(r'\b(?:I|[Mm]e|[Mm]y|[Mm]ine|[Ww]e|us|[Oo]ur|[Oo]urs)\b')
MATH = re.compile(r'\$\$.*?\$\$|\$[^$\n]*\$|\\\(.*?\\\)|\\\[.*?\\\]', re.S)
ROMAN_LABELS = {
    'Type', 'Table', 'Column', 'Panel', 'Figure', 'Model', 'Phase', 'Stage',
    'Part', 'Chapter', 'Section', 'Appendix', 'Study', 'Experiment', 'Wave',
    'Step', 'Tier', 'Class', 'Title', 'War', 'Specification', 'Hypothesis',
}
ROMAN_FOLLOWERS = {'error', 'errors', 'and', 'or', 'to', 'through', 'vs', 'versus'}


def is_roman_numeral(text: str, start: int, end: int) -> bool:
    """'Type I error', 'Table I', 'type I and type II', '(I)' -- not the pronoun."""
    if text[end:end + 1] == ')':
        return True
    before = re.search(r'(\w+)\W*$', text[:start])
    previous = before.group(1) if before else ''
    if previous in ROMAN_LABELS:
        return True
    after = re.match(r'(\s*)(\w*)', text[end:])
    if previous.lower() in {w.lower() for w in ROMAN_LABELS}:
        # lowercase label: "type I error" yes, "this section I estimate" no
        return not after.group(1) or after.group(2).lower() in ROMAN_FOLLOWERS
    return False


def count_first_person(text: str) -> int:
    text = MATH.sub(' ', text)
    return sum(1 for m in FIRST_PERSON.finditer(text)
               if m.group() != 'I' or not is_roman_numeral(text, m.start(), m.end()))


NUMBER = re.compile(
    r'(?<![\w.])[-\u2212]?(?:\d{1,3}(?:,\d{3})+(?:\.\d+)?|\d+(?:\.\d+)?|\.\d+)'
    r'(?:[eE][-+\u2212]?\d+)?'
)
# Numbers that label things rather than report them: "Table 2",
# "Columns (1)-(3)", "Tables 2 and 3", "Appendix B4", "pp. 12-15", "R^2",
# "x_{it}", "(3)", and list markers.
_REF = r'[(\[]?[A-Z]?\d+[a-z]?[)\]]?'
LABEL_REFERENCE = re.compile(
    r'\b(?:(?i:tables?|columns?|cols?\.|figures?|figs?\.|panels?|sections?|secs?\.|'
    r'chapters?|ch\.|appendix|appendices|app\.|equations?|eqs?\.|footnotes?|'
    r'specifications?)|Models?|Hypothes[ie]s|Steps?|Rounds?|Waves?|Stud(?:y|ies)|'
    r'Experiments?|Notes?|Pages?|pp?\.)\s*' + _REF +
    r'(?:\s*(?:,|and|&|or|to|through|-|\u2013)\s*' + _REF + r')*'
)
NOT_DATA = re.compile(
    r'\d*[\^_]\{[^}]*\}|\d*[\^_][-\u2212]?\d+'  # powers and subscripts: R^2, 10^{-3}
    r'|\(\d{1,2}\)'                           # enumerators: (1), (3)
    r'|^\s*\d{1,2}[.)](?=\s)'                 # list markers at line start
    r'|(?<=[.!?:]\s)\d{1,2}[.)](?=\s)',       # ...and after a sentence
    re.M,
)


def extract_numbers(text: str) -> set:
    """Specific values in the text, ignoring labels like 'Table 2'."""
    text = NOT_DATA.sub(' ', LABEL_REFERENCE.sub(' ', text))
    found = set()
    for m in NUMBER.finditer(text):
        raw = m.group().replace(',', '').replace('\u2212', '-').rstrip('.')
        try:
            found.add(format(Decimal(raw).normalize(), 'f'))  # '40', not '4E+1'
        except InvalidOperation:
            continue
    return found


HEDGES = [
    r'\bmight\b', r'\bcould\b', r'\bperhaps\b', r'\bpossibly\b',
    r'\bpotentially\b', r'\bappear(?:s|ed)?\b(?!\s+in\b)', r'\bseems?\b',
    r'(?<!\)\s)\bsuggests?\b', r'\bapproximately\b', r'\bbroadly\b',
    r'\bgenerally\b', r'\btends?\b', r'\bsomewhat\b', r'\brelatively\b',
    r'\barguably\b', r'\bto some extent\b',
    r'\bcannot be (?:entirely |fully )?ruled out\b',
    r'\bit is worth noting\b', r'\bit is important to\b',
]


def count_hedge_words(text: str) -> int:
    modal_may = len(re.findall(r'\bmay\b', text))  # lowercase only: not the month
    return modal_may + sum(len(re.findall(h, text, re.IGNORECASE)) for h in HEDGES)


def per_100_words(count: int, words: int) -> float:
    return count / words * 100 if words else 0.0


def length_spread(sentences: list):
    """Coefficient of variation of sentence length; None if under 3 sentences."""
    lengths = [count_words(s) for s in sentences]
    if len(lengths) < 3 or statistics.mean(lengths) == 0:
        return None
    return statistics.pstdev(lengths) / statistics.mean(lengths)


STOCK_OPENER = re.compile(
    r'^["\'\u201c\u2018(]?(?:Moreover|Furthermore|Additionally|In addition|Notably|'
    r'Importantly|Crucially|Overall|Ultimately)\b'
)

SUMMARY_CLOSER = re.compile(
    r'^["\'\u201c\u2018(]?(?:This|These|Such|Together|Taken together|Overall|In sum|'
    r'In short|Collectively|Ultimately)\b[^.]{0,60}?\b(?:suggests?|indicates?|'
    r'underscores?|highlights?|demonstrates?|illustrates?|shows?|reveals?|'
    r'points? to|speaks? to|reflects?|emphasi[sz]es?|confirms?|impl(?:y|ies)|'
    r'signals?|attests? to)\b'
)
REPORTS_RESULT = re.compile(r'\d|\b(?:Table|Figure|Column|Panel)\b')


def count_stock_openers(sentences: list) -> int:
    return sum(1 for s in sentences if STOCK_OPENER.match(s))


def summary_closers(text: str):
    """(paragraphs ending in a summary closer, paragraphs with 2+ sentences)."""
    eligible = closers = 0
    for p in paragraphs(text):
        sentences = split_sentences(p)
        if len(sentences) < 2:
            continue
        eligible += 1
        last = sentences[-1]
        if SUMMARY_CLOSER.match(last) and not REPORTS_RESULT.search(last):
            closers += 1
    return closers, eligible


# --- Analysis ---------------------------------------------------------------

def analyze(original: str, revised: str, mode: str = 'edit') -> dict:
    rewrite = mode == 'rewrite'
    results = {}
    orig_sents, rev_sents = all_sentences(original), all_sentences(revised)

    # 1. Word count
    orig_wc, rev_wc = count_words(original), count_words(revised)
    wc_change = (rev_wc - orig_wc) / orig_wc * 100 if orig_wc > 0 else 0
    note = ''
    if mode != 'edit':
        note = f' (reported only in {mode} mode)'
    elif wc_change > 15:
        note = ' — likely filler added'
    elif wc_change < -15:
        note = ' — shorter; check that nothing substantive was cut'
    results['word_count'] = {
        'original': orig_wc,
        'revised': rev_wc,
        'change_pct': round(wc_change, 1),
        'checked': mode == 'edit',
        'flag': mode == 'edit' and wc_change > 15,
        'message': f"Word count changed {wc_change:+.1f}%" + note,
    }

    # 2. First-person pronouns
    orig_fp, rev_fp = count_first_person(original), count_first_person(revised)
    if rewrite:
        fp_flag = orig_fp > 0 and rev_fp == 0
    else:
        fp_flag = orig_fp > 0 and (rev_fp == 0 or
                                   (orig_fp - rev_fp >= 2 and rev_fp <= 0.75 * orig_fp))
    results['first_person'] = {
        'original': orig_fp,
        'revised': rev_fp,
        'flag': fp_flag,
        'message': f"First-person pronouns: {orig_fp} → {rev_fp}"
                   + (" — voice may be erased" if fp_flag else ""),
    }

    # 3. Specific numbers
    orig_nums, rev_nums = extract_numbers(original), extract_numbers(revised)
    lost = sorted(orig_nums - rev_nums, key=lambda n: (len(n), n))
    results['numbers'] = {
        'original': len(orig_nums),
        'revised': len(rev_nums),
        'lost': lost,
        'flag': bool(lost),
        'message': f"Specific numbers: {len(orig_nums)} → {len(rev_nums)}"
                   + (f" — missing from revision: {', '.join(lost[:5])}" if lost else ""),
    }

    # 4. Hedges
    orig_h, rev_h = count_hedge_words(original), count_hedge_words(revised)
    orig_d, rev_d = per_100_words(orig_h, orig_wc), per_100_words(rev_h, rev_wc)
    if rewrite:
        hedge_flag = rev_d >= 3.0 and rev_d > orig_d
    else:
        hedge_flag = rev_h - orig_h >= 2 and rev_d > orig_d
    results['hedge_words'] = {
        'original': orig_h,
        'revised': rev_h,
        'density_original': round(orig_d, 2),
        'density_revised': round(rev_d, 2),
        'flag': hedge_flag,
        'message': f"Hedge words: {orig_h} → {rev_h} "
                   f"({orig_d:.1f} → {rev_d:.1f} per 100 words)"
                   + (" — confidence may be eroded" if hedge_flag else ""),
    }

    # 5. Sentence length spread
    orig_cv, rev_cv = length_spread(orig_sents), length_spread(rev_sents)
    if rev_cv is None:
        spread_flag = False
    elif rewrite:
        spread_flag = (len(rev_sents) >= 4 and rev_cv < 0.25
                       and (orig_cv is None or rev_cv < orig_cv))
    else:
        spread_flag = orig_cv is not None and rev_cv < 0.6 * orig_cv and rev_cv < 0.3
    fmt = lambda v: 'n/a' if v is None else f"{v:.2f}"
    results['sentence_variance'] = {
        'original': None if orig_cv is None else round(orig_cv, 2),
        'revised': None if rev_cv is None else round(rev_cv, 2),
        'flag': spread_flag,
        'message': f"Sentence length spread (CV): {fmt(orig_cv)} → {fmt(rev_cv)}"
                   + (" — sentences becoming uniform" if spread_flag else ""),
    }

    # 6. Stock transitions
    orig_t, rev_t = count_stock_openers(orig_sents), count_stock_openers(rev_sents)
    orig_ts = orig_t / len(orig_sents) if orig_sents else 0.0
    rev_ts = rev_t / len(rev_sents) if rev_sents else 0.0
    if rewrite:
        trans_flag = len(rev_sents) >= 4 and rev_ts >= 0.3 and rev_ts > orig_ts
    else:
        trans_flag = rev_t > orig_t and rev_ts - orig_ts >= 0.1 - 1e-9
    results['transitions'] = {
        'original': orig_t,
        'revised': rev_t,
        'flag': trans_flag,
        'message': f"Sentences opening with stock transitions: {orig_t} → {rev_t}"
                   + (" — mechanical rhythm" if trans_flag else ""),
    }

    # 7. Summary closers
    (orig_c, _), (rev_c, rev_elig) = summary_closers(original), summary_closers(revised)
    if rewrite:
        closer_flag = rev_elig >= 2 and rev_c / rev_elig >= 0.5 and rev_c > orig_c
    else:
        closer_flag = rev_c > orig_c
    results['summary_closers'] = {
        'original': orig_c,
        'revised': rev_c,
        'flag': closer_flag,
        'message': f"Paragraphs ending in a summary closer: {orig_c} → {rev_c}"
                   + (" — template paragraphs" if closer_flag else ""),
    }

    flags = sum(1 for r in results.values() if r['flag'])
    results['summary'] = {
        'mode': mode,
        'flags_triggered': flags,
        'total_checks': 7 if mode == 'edit' else 6,
        'homogenization_warning': flags >= 2,
        'verdict': "HOMOGENIZATION WARNING" if flags >= 2
                   else "MINOR CONCERNS" if flags == 1
                   else "CLEAN",
    }
    return results


# --- CLI --------------------------------------------------------------------

def load_text(path: str) -> str:
    p = Path(path)
    try:
        return p.read_text(encoding='utf-8')
    except UnicodeDecodeError:
        return p.read_text(encoding='utf-8', errors='replace')


def main():
    parser = argparse.ArgumentParser(
        description="Check for homogenization signals between original and revised text."
    )
    parser.add_argument('--text', nargs=2, metavar=('ORIGINAL', 'REVISED'),
                        help='Pass original and revised text directly as arguments')
    parser.add_argument('--mode', choices=['edit', 'substantive', 'rewrite'], default='edit',
                        help="match the edit type: edit (default), substantive, rewrite")
    parser.add_argument('--latex', action='store_true',
                        help='Strip LaTeX comments and citation/reference commands')
    parser.add_argument('--json', action='store_true', help='Print results as JSON')
    parser.add_argument('files', nargs='*',
                        help='Two file paths: original.txt revised.txt')

    args = parser.parse_args()

    if args.text and args.files:
        parser.error("give either --text or two files, not both")
    if args.text:
        original, revised = args.text
    elif len(args.files) == 2:
        try:
            original, revised = load_text(args.files[0]), load_text(args.files[1])
        except OSError as e:
            parser.error(str(e))
    else:
        parser.error("give two files (original.txt revised.txt) or --text 'original' 'revised'")
    if args.latex or any(Path(f).suffix.lower() == '.tex' for f in args.files):
        original, revised = strip_latex(original), strip_latex(revised)

    results = analyze(original, revised, args.mode)

    if args.json:
        print(json.dumps(results, ensure_ascii=False, indent=2))
        return

    summary = results['summary']
    print(f"\n=== Revision Guard: Diff Check ({summary['mode']} mode) ===\n")
    for key, value in results.items():
        if key == 'summary':
            continue
        marker = '[--]' if not value.get('checked', True) else '[!!]' if value['flag'] else '[ok]'
        print(f"  {marker} {value['message']}")

    print(f"\n  {'[!!]' if summary['homogenization_warning'] else '[ok]'} "
          f"Verdict: {summary['verdict']} "
          f"({summary['flags_triggered']}/{summary['total_checks']} checks flagged)")
    print()


if __name__ == '__main__':
    if hasattr(sys.stdout, 'reconfigure'):
        sys.stdout.reconfigure(encoding='utf-8', errors='replace')
    main()
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