coroboros/agent-skills / skills/humanize-en
humanize-en
VerifiedRemove AI writing tells from English prose while preserving meaning, structure, code, links and quotations. Use for humanize this, remove AI slop and polish the English on inline text or prose files. Optional -f BRAND-VOICE.md applies brand rules with explicit mechanical and semantic coverage. Inherit authorized rewrite scope; audit/propose remains read-only. Structural README work belongs to write-clear-readme.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.1 KB |
| eval-corpus/brand-voice/brand-allcaps-01.json | config | 1.2 KB |
| eval-corpus/brand-voice/brand-clean-01.json | config | 1.3 KB |
| eval-corpus/brand-voice/brand-lexicon-01.json | config | 911 B |
| eval-corpus/brand-voice/brand-pronouns-01.json | config | 978 B |
| eval-corpus/brand-voice/brand-rewrite-rules-01.json | config | 946 B |
| eval-corpus/brand-voice/brand-rhetoric-01.json | config | 1.1 KB |
| eval-corpus/samples/clean-prose-01.json | config | 417 B |
| eval-corpus/samples/docs-intro-01.json | config | 631 B |
| eval-corpus/samples/hero-landing-01.json | config | 637 B |
| eval-corpus/samples/release-notes-01.json | config | 571 B |
| evals/evals.json | config | 2.8 KB |
| references/output-formats.md | markdown | 1.7 KB |
| references/patterns.md | markdown | 18.3 KB |
| references/schemas.md | markdown | 10.7 KB |
| references/voice.md | markdown | 2.8 KB |
| scripts/__init__.py | script | 0 B |
| scripts/brand_prescan.py | script | 28.0 KB |
| scripts/eval_patterns.pyexecutable | script | 5.3 KB |
| scripts/prescan.pyexecutable | script | 11.0 KB |
| scripts/utils.py | script | 1.6 KB |
| scripts/validate.py | script | 7.0 KB |
scripts/validate.py
View on GitHub#!/usr/bin/env python3
"""
validate.py — post-rewrite validation gate for humanize-en.
Runs the deterministic prescan (universal + optional brand) on a file that
has just been rewritten and reports residuals or regressions. Designed to be
called by SKILL.md right after `Edit` applies, before declaring the rewrite
complete.
Usage:
validate.py <file>
validate.py --brand path/to/BRAND-VOICE.md <file>
validate.py --baseline pre-rewrite-hits.json <file>
validate.py --strict-code-only <file>
Outcomes (stdout JSON):
status="clean" — zero hits remain. Rewrite is shippable.
status="residuals" — hits remain but no new ones were introduced relative
to the baseline. User decides: accept or iterate.
status="regression" — at least one hit appears that was not in the baseline.
Rewrite introduced new tells; revert or fix-forward.
When --baseline is omitted, every remaining hit is reported as a residual
(no regression check possible without a pre-rewrite snapshot).
Output schema (references/schemas.md § validate result):
{
"path": "<file>",
"status": "clean" | "residuals" | "regression",
"residuals": [<prescan-hit>, ...],
"new_hits": [<prescan-hit>, ...], # only when status=="regression"
"summary": {
"total_residuals": int,
"universal_residuals": int,
"brand_residuals": int,
"new_hit_count": int
}
}
Exit codes:
0 status="clean" or status="residuals"
1 status="regression"
2 argument or I/O error
Requires Python 3.7+. No third-party dependencies.
"""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent))
from prescan import scan as prescan_scan # noqa: E402
class _ValidateArgParser(argparse.ArgumentParser):
def error(self, message):
print(f"error: {message}", file=sys.stderr)
print(
"usage: validate.py <file> [--brand <doc>] [--baseline <hits.json>] [--strict-code-only]",
file=sys.stderr,
)
sys.exit(2)
def _hit_signature(hit):
"""Stable identity for hit-set comparisons. A hit is identified by
`(pattern, snippet)`.
Line numbers are deliberately omitted: the rewrite step can shorten or
lengthen the file, shifting every subsequent line. A signature that
included the line would treat the same lexical violation at a new line
number as a regression. The snippet alone (~20 chars on each side of the
match per `prescan.py:scan`) usually disambiguates same-pattern matches
that genuinely live in different sentences. Two identical sentences on
different lines collapse into one signature, which is the right
trade-off — regressions are about *new* lexical violations appearing,
not duplicate-count drift."""
return (
str(hit.get("pattern")),
(hit.get("snippet") or "").strip(),
)
def validate(path, brand_path=None, baseline_hits=None, strict_code_only=False, rules_json=None):
"""Re-scan `path` and return a validation result dict per the schema above."""
text = Path(path).read_text(encoding="utf-8")
if brand_path and rules_json:
raise ValueError("choose --brand or --rules-json, not both")
has_brand = bool(brand_path or rules_json)
residuals = prescan_scan(text, strict_code_only=strict_code_only, attach_source=has_brand)
if has_brand:
from brand_prescan import load_brand_rules, load_resolved_rules, scan_brand
rules = load_resolved_rules(rules_json) if rules_json else load_brand_rules(brand_path)
residuals.extend(scan_brand(text, rules, strict_code_only=strict_code_only))
universal_count = sum(1 for h in residuals if h.get("source") != "brand")
brand_count = sum(1 for h in residuals if h.get("source") == "brand")
new_hits = []
if baseline_hits is not None:
baseline_sigs = {_hit_signature(h) for h in baseline_hits}
new_hits = [h for h in residuals if _hit_signature(h) not in baseline_sigs]
if not residuals:
status = "clean"
elif new_hits:
status = "regression"
else:
status = "residuals"
result = {
"path": str(path),
"status": status,
"residuals": residuals,
"summary": {
"total_residuals": len(residuals),
"universal_residuals": universal_count,
"brand_residuals": brand_count,
"new_hit_count": len(new_hits),
},
}
if status == "regression":
result["new_hits"] = new_hits
return result
def main():
parser = _ValidateArgParser(
description=(__doc__ or "").split("\n\n")[0],
prog="validate.py",
)
parser.add_argument("path", help="path to the rewritten prose file")
brand_input = parser.add_mutually_exclusive_group()
brand_input.add_argument("--brand", metavar="<voice-doc>",
help="BRAND-VOICE.md to enforce alongside universal patterns")
brand_input.add_argument("--rules-json", help="resolved rules from extract_rules.py --resolved-json")
parser.add_argument("--baseline", metavar="<hits.json>",
help="prescan output captured BEFORE the rewrite, "
"for regression detection")
parser.add_argument("--strict-code-only", action="store_true",
help="blank every fenced block (disables pseudo-blocks)")
args = parser.parse_args()
target = Path(args.path)
if not target.is_file():
print(f"error: file not found: {args.path}", file=sys.stderr)
return 2
baseline = None
if args.baseline:
baseline_path = Path(args.baseline)
if not baseline_path.is_file():
print(f"error: baseline not found: {args.baseline}", file=sys.stderr)
return 2
try:
baseline = json.loads(baseline_path.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
print(f"error: cannot read baseline: {exc}", file=sys.stderr)
return 2
if not isinstance(baseline, list):
print("error: baseline must be a JSON array of prescan hits", file=sys.stderr)
return 2
try:
result = validate(
str(target),
brand_path=args.brand,
baseline_hits=baseline,
strict_code_only=args.strict_code_only,
rules_json=args.rules_json,
)
except FileNotFoundError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
except UnicodeDecodeError as exc:
print(f"error: file is not valid UTF-8: {exc}", file=sys.stderr)
return 2
except OSError as exc:
print(f"error: cannot read file: {exc}", file=sys.stderr)
return 2
except ValueError as exc:
print(f"error: invalid brand rules: {exc}", file=sys.stderr)
return 2
print(json.dumps(result, ensure_ascii=False, indent=2))
return 1 if result["status"] == "regression" else 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: 471k | 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: 471k | 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: 471k | 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 |