Skip to content

Poisoneddiety/claude-skills-for-humanities / skills/academic-prose-audit

academic-prose-audit

Verified

Audit and revise drafted academic legal prose for propositional compression, mechanical sentence rhythm, and AI register, while preserving formal academic voice and OSCOLA conventions. Fixes the defect where too much meaning is left for the reader to reconstruct. Use this on any draft paper, response paper, seminar piece, or long note before submission, and whenever the user says a draft reads mechanically, sounds like AI, or needs humanising. Do NOT use for first drafts, exam answers, or casual chat.

FileKindSize
SKILL.mdskill md7.3 KB
references/patterns.mdmarkdown8.9 KB
scripts/audit.pyscript14.0 KB

scripts/audit.py

View on GitHub
#!/usr/bin/env python3
"""
Deterministic prose metrics for academic legal writing.

Reports the mechanical defects that should never depend on a model noticing them:
em dash rate, sentence-length uniformity, nominalisation density, banned register,
hedge stacking, and connective filler.

Usage:
    python audit.py draft.md
    python audit.py draft.txt --json
    cat draft.md | python audit.py -

Stdlib only. Nothing here makes a judgement call; judgement is the second pass.
"""

import argparse
import json
import re
import statistics
import sys
from collections import Counter

# ---------------------------------------------------------------- register

# Words and phrases that read as AI-register or as filler in academic legal prose.
# Not all are wrong in every context; the script flags, a human decides.
BANNED_WORDS = [
    "delve", "delves", "delving",
    "landscape",           # when metaphorical
    "robust",
    "seamless", "seamlessly",
    "underscore", "underscores", "underscored",
    "pivotal",
    "crucial",
    "navigate", "navigating",   # when metaphorical
    "leverage", "leveraging",   # as verb
    "streamline", "streamlined",
    "foster", "fostering",
    "utilise", "utilize", "utilises", "utilizes",
    "myriad",
    "tapestry",
    "realm",
    "paradigm",
    "holistic",
    "multifaceted",
    "intricate",
    "vibrant",
    "compelling",
    "testament",
]

BANNED_PHRASES = [
    "it is worth noting",
    "it is important to note",
    "it should be noted that",
    "plays a crucial role",
    "plays a vital role",
    "highlights the importance",
    "sheds light on",
    "in today's",
    "in an era",
    "at its core",
    "the fact that",
    "in order to",
    "due to the fact",
    "a wide range of",
    "a growing body of",
    "it is clear that",
    "needless to say",
    "when it comes to",
    "serves as a",
    "stands as a",
    "cannot be overstated",
    "double-edged sword",
    "delicate balance",
    "rich tapestry",
]

# Connective filler used as sentence openers.
FILLER_OPENERS = [
    "moreover", "furthermore", "additionally", "notably", "importantly",
    "significantly", "indeed", "ultimately", "crucially", "consequently",
]

# Hedge words. One is fine and often correct. Stacked, they cancel.
HEDGES = [
    "may", "might", "could", "possibly", "potentially", "arguably",
    "perhaps", "seemingly", "somewhat", "relatively", "generally",
    "often", "typically", "tends to", "appears to", "suggests",
]

# Nominalisation suffixes. High density buries the actor.
NOMINAL_SUFFIXES = ("tion", "sion", "ment", "ance", "ence", "ity", "ness", "ism")

# Words legitimately ending in those suffixes that are not nominalisations
# of interest in legal prose, or are unavoidable terms of art.
NOMINAL_EXEMPT = {
    "constitution", "constitutional", "jurisdiction", "jurisdictional",
    "corporation", "legislation", "regulation", "provision", "section",
    "convention", "commission", "petition", "opinion", "question",
    "information", "position", "condition", "relation", "operation",
    "authority", "liability", "equity", "entity", "majority", "minority",
    "capacity", "validity", "legality", "necessity", "community",
    "government", "agreement", "instrument", "judgment", "judgement",
    "amendment", "settlement", "document", "argument", "element",
    "evidence", "difference", "reference", "existence", "sentence",
    "circumstance", "importance", "performance", "insurance",
    "business", "witness", "fairness",
    "formalism", "realism", "positivism", "federalism",
}

# Constructions with a strong AI signature.
SIGNATURE_PATTERNS = [
    (r"\bnot (just|merely|only) [^,.;]{2,60},? but\b", "not-merely-but construction"),
    (r"\bit'?s not (just|merely|only|about)\b", "it's-not-X-it's-Y construction"),
    (r"\bisn'?t (just|merely|only)\b", "isn't-just construction"),
    (r"\bfrom [^,.;]{2,40} to [^,.;]{2,40},? (the|this|these)\b", "false range"),
    (r"\bwhether .{2,60} or .{2,60}, (the|this|it)\b", "whether-or framing device"),
    (r"\b(may|might|could) (potentially|possibly|perhaps)\b", "stacked hedge"),
    (r"\b(can|could) (potentially|possibly)\b", "stacked hedge"),
    (r"\bin the (realm|sphere|domain|arena) of\b", "abstract-place filler"),
]


# ---------------------------------------------------------------- parsing

def split_paragraphs(text):
    paras = [p.strip() for p in re.split(r"\n\s*\n", text)]
    return [p for p in paras if p and not p.startswith("#")]


ABBREVIATIONS = [
    "v", "Ltd", "Pvt", "No", "Nos", "Art", "Arts", "s", "ss", "para", "paras",
    "cf", "ed", "eds", "edn", "Ors", "Anr", "Co", "Inc", "J", "JJ", "CJ",
    "i.e", "e.g", "etc", "Vol", "p", "pp", "Rs", "Sec", "Cl", "r", "reg",
    "Hon", "Mr", "Mrs", "Ms", "Dr", "Prof", "St", "cl", "Ch", "Pt", "Sch",
]

# Match an abbreviation only as a whole token: preceded by start/space/bracket.
_ABBR_RE = re.compile(
    r"(?<![A-Za-z])(" + "|".join(re.escape(a) for a in ABBREVIATIONS) + r")\.",
)


def split_sentences(text):
    """Approximate sentence splitting, protecting common legal abbreviations.

    Abbreviations are matched as whole tokens. A naive substring replace would
    corrupt ordinary words — 's.' would fire inside 'structures.' and destroy
    the sentence boundary.
    """
    protected = _ABBR_RE.sub(lambda m: m.group(1) + "\x00", text)
    # Also protect initials such as 'A. K. Roy' and numbered pinpoints '12.'
    protected = re.sub(r"(?<![A-Za-z])([A-Z])\.(?=\s+[A-Z])",
                       lambda m: m.group(1) + "\x00", protected)
    protected = re.sub(r"(\d)\.(?=\s*\d)",
                       lambda m: m.group(1) + "\x00", protected)

    parts = re.split(r"(?<=[.!?])[\"')\]]*\s+(?=[A-Z\"'(\[])", protected)
    out = []
    for p in parts:
        s = p.replace("\x00", ".").strip()
        if s:
            out.append(s)
    return out


def words(text):
    return re.findall(r"[A-Za-z][A-Za-z'\-]*", text)


# ---------------------------------------------------------------- analysis

def analyse(text):
    paras = split_paragraphs(text)
    body = "\n\n".join(paras)
    sents = split_sentences(body)
    all_words = words(body)
    wc = len(all_words)
    lower = body.lower()
    per_k = (lambda n: round(n * 1000 / wc, 2)) if wc else (lambda n: 0.0)

    r = {"word_count": wc, "sentence_count": len(sents),
         "paragraph_count": len(paras)}

    # -- em dashes and their relatives
    em = body.count("\u2014")
    en_between = len(re.findall(r"\w\s*\u2013\s*\w", body))
    double_hyphen = body.count("--")
    r["em_dash"] = {
        "count": em, "per_1000_words": per_k(em),
        "budget_per_1000": 1.0,
        "over_budget": per_k(em) > 1.0,
        "en_dash_as_parenthetical": en_between,
        "double_hyphen": double_hyphen,
    }

    # -- sentence length distribution
    lens = [len(words(s)) for s in sents]
    if lens:
        mean = statistics.mean(lens)
        sd = statistics.pstdev(lens) if len(lens) > 1 else 0.0
        # longest run of consecutive sentences within 5 words of each other
        run, longest = 1, 1
        for i in range(1, len(lens)):
            if abs(lens[i] - lens[i - 1]) <= 5:
                run += 1
                longest = max(longest, run)
            else:
                run = 1
        r["sentence_length"] = {
            "mean": round(mean, 1),
            "stdev": round(sd, 1),
            "min": min(lens), "max": max(lens),
            "longest_uniform_run": longest,
            "uniform_run_limit": 3,
            "too_uniform": sd < 7.0 or longest > 3,
            "distribution": lens,
        }
    else:
        r["sentence_length"] = {}

    # -- paragraph uniformity (in sentences)
    plens = [len(split_sentences(p)) for p in paras]
    if plens:
        psd = statistics.pstdev(plens) if len(plens) > 1 else 0.0
        r["paragraph_length"] = {
            "sentences_per_paragraph": plens,
            "mean": round(statistics.mean(plens), 1),
            "stdev": round(psd, 1),
            "too_uniform": psd < 1.0 and len(plens) > 3,
        }

    # -- nominalisation density
    noms = []
    for w in all_words:
        lw = w.lower()
        if lw in NOMINAL_EXEMPT or len(lw) < 7:
            continue
        if lw.endswith(NOMINAL_SUFFIXES):
            noms.append(lw)
    r["nominalisation"] = {
        "count": len(noms),
        "per_1000_words": per_k(len(noms)),
        "guideline_max_per_1000": 45.0,
        "over_guideline": per_k(len(noms)) > 45.0,
        "most_common": Counter(noms).most_common(12),
    }

    # -- banned register
    wordhits = Counter()
    for w in all_words:
        lw = w.lower()
        if lw in BANNED_WORDS:
            wordhits[lw] += 1
    phrasehits = Counter()
    for ph in BANNED_PHRASES:
        n = lower.count(ph)
        if n:
            phrasehits[ph] = n
    r["banned_register"] = {
        "word_hits": dict(wordhits.most_common()),
        "phrase_hits": dict(phrasehits.most_common()),
        "total": sum(wordhits.values()) + sum(phrasehits.values()),
    }

    # -- filler sentence openers
    openers = Counter()
    for s in sents:
        m = re.match(r"\s*([A-Za-z]+)", s)
        if m and m.group(1).lower() in FILLER_OPENERS:
            openers[m.group(1).lower()] += 1
    r["filler_openers"] = {
        "hits": dict(openers.most_common()),
        "total": sum(openers.values()),
        "per_1000_words": per_k(sum(openers.values())),
    }

    # -- signature constructions
    sig = []
    for pat, label in SIGNATURE_PATTERNS:
        for m in re.finditer(pat, body, flags=re.I):
            sig.append({"pattern": label,
                        "text": m.group(0)[:90],
                        "char_offset": m.start()})
    r["signature_constructions"] = {"count": len(sig), "hits": sig[:40]}

    # -- hedge stacking, per sentence
    stacked = []
    for i, s in enumerate(sents):
        sl = s.lower()
        n = sum(1 for h in HEDGES if re.search(r"\b" + re.escape(h) + r"\b", sl))
        if n >= 3:
            stacked.append({"sentence_index": i, "hedges": n, "text": s[:140]})
    r["hedge_stacking"] = {"sentences": stacked, "count": len(stacked)}

    # -- passive approximation
    passive = len(re.findall(
        r"\b(is|are|was|were|be|been|being)\s+(\w+ed|\w+en)\b", body, flags=re.I))
    r["passive_approx"] = {
        "count": passive, "per_1000_words": per_k(passive),
        "note": "Passive is often correct in legal prose. Flag only, do not auto-fix.",
    }

    # -- tricolon
    tri = len(re.findall(r"\b\w+,\s+\w+,?\s+and\s+\w+\b", body))
    r["tricolon"] = {"count": tri, "per_1000_words": per_k(tri)}

    # -- overlong sentences worth splitting
    r["long_sentences"] = [
        {"index": i, "words": lens[i], "text": sents[i][:170]}
        for i in range(len(sents)) if lens and lens[i] > 55
    ]

    return r


def render(r):
    L = []
    a = L.append
    a("PROSE AUDIT — deterministic pass")
    a("=" * 52)
    a(f"{r['word_count']} words · {r['sentence_count']} sentences · "
      f"{r['paragraph_count']} paragraphs")
    a("")

    e = r["em_dash"]
    flag = "OVER BUDGET" if e["over_budget"] else "ok"
    a(f"Em dashes            {e['count']} ({e['per_1000_words']}/1k, budget 1.0/1k) [{flag}]")
    if e["en_dash_as_parenthetical"]:
        a(f"  en dash as parenthetical: {e['en_dash_as_parenthetical']}")
    if e["double_hyphen"]:
        a(f"  double hyphen: {e['double_hyphen']}")

    s = r.get("sentence_length") or {}
    if s:
        flag = "TOO UNIFORM" if s["too_uniform"] else "ok"
        a(f"Sentence length      mean {s['mean']}, sd {s['stdev']}, "
          f"range {s['min']}-{s['max']} [{flag}]")
        a(f"  longest run of similar-length sentences: {s['longest_uniform_run']} "
          f"(limit {s['uniform_run_limit']})")

    p = r.get("paragraph_length") or {}
    if p:
        flag = "TOO UNIFORM" if p["too_uniform"] else "ok"
        a(f"Paragraph length     mean {p['mean']} sentences, sd {p['stdev']} [{flag}]")

    n = r["nominalisation"]
    flag = "HIGH" if n["over_guideline"] else "ok"
    a(f"Nominalisation       {n['count']} ({n['per_1000_words']}/1k, "
      f"guide <{n['guideline_max_per_1000']}) [{flag}]")
    if n["most_common"]:
        a("  " + ", ".join(f"{w}×{c}" for w, c in n["most_common"][:8]))

    b = r["banned_register"]
    a(f"Banned register      {b['total']} hits")
    for w, c in list(b["word_hits"].items())[:12]:
        a(f"  word   '{w}' ×{c}")
    for ph, c in list(b["phrase_hits"].items())[:12]:
        a(f"  phrase '{ph}' ×{c}")

    f = r["filler_openers"]
    a(f"Filler openers       {f['total']} ({f['per_1000_words']}/1k)")
    for w, c in f["hits"].items():
        a(f"  '{w.title()},' ×{c}")

    sg = r["signature_constructions"]
    a(f"AI signature forms   {sg['count']}")
    for h in sg["hits"][:12]:
        a(f"  [{h['pattern']}] {h['text']}")

    h = r["hedge_stacking"]
    a(f"Hedge stacking       {h['count']} sentences with 3+ hedges")
    for x in h["sentences"][:6]:
        a(f"  s{x['sentence_index']} ({x['hedges']}): {x['text']}")

    pa = r["passive_approx"]
    a(f"Passive (approx)     {pa['count']} ({pa['per_1000_words']}/1k) — flag only")
    a(f"Tricolon             {r['tricolon']['count']} "
      f"({r['tricolon']['per_1000_words']}/1k)")

    ls = r["long_sentences"]
    a(f"Sentences >55 words  {len(ls)}")
    for x in ls[:8]:
        a(f"  s{x['index']} ({x['words']}w): {x['text']}…")

    a("")
    a("This pass is mechanical. It cannot see buried actors, elided inferential")
    a("steps, or citations doing an argument's work. Run the judgement pass next.")
    return "\n".join(L)


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("path", help="file to audit, or - for stdin")
    ap.add_argument("--json", action="store_true", help="emit raw JSON")
    args = ap.parse_args()

    if args.path == "-":
        text = sys.stdin.read()
    else:
        with open(args.path, encoding="utf-8") as fh:
            text = fh.read()

    if not text.strip():
        print("Empty input.", file=sys.stderr)
        return 1

    result = analyse(text)
    print(json.dumps(result, indent=2) if args.json else render(result))
    return 0


if __name__ == "__main__":
    sys.exit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall