Poisoneddiety/claude-skills-for-humanities / skills/academic-prose-audit
academic-prose-audit
VerifiedAudit 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.3 KB |
| references/patterns.md | markdown | 8.9 KB |
| scripts/audit.py | script | 14.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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |