conorbronsdon__avoid-ai-writing/CONTRIBUTING.md

Contributing

Thanks for helping improve this skill. It teaches an LLM (and now a deterministic engine) to spot and fix AI-writing tells. Contributions are welcome — a few things keep the project coherent.

How the repo fits together

Path	What it holds
SKILL.md	Entry instructions, severity tiers, output formats, and guardrails.
references/patterns.md	Canonical pattern catalog, word tiers, context and voice profiles.
detector/patterns.js	The deterministic engine — the executable subset of the rules.
detector/CATEGORIES.md	The map between references/patterns.md rules and detector types. Keep it current.
README.md	The pitch and the numbered prose-pattern list.
cursor-rules/, plugins/	Editor and tool integrations.

Adding or changing a rule

First decide which kind of rule it is:

• Regex-detectable (a phrase, a character, a structural shape) → add it to references/patterns.md, add the detection to detector/patterns.js with a new type, and add a row to detector/CATEGORIES.md. Cover it with a fixture in detector/patterns.test.js (both a true positive and a case that must not fire).
• Judgment-only (needs reading for meaning — tone, structure, name-dropping) → add it to references/patterns.md prose and list it under "Skill-only" in detector/CATEGORIES.md. There is no detector type for these.

If you are unsure which it is, open an issue first and we will sort it out. The pattern proposal form asks for what triage needs, including the example that must stay clean.

Precision over recall

This skill is deliberately biased toward false negatives: a rule that wrongly flags ordinary human writing is worse than one that misses a tell, because false positives erode trust in every other rule. Before proposing a rule, ask who would get flagged by mistake, and add carve-outs for the legitimate cases. A signal that fires on most normal prose is not worth adding.

Cite your sources

If your rule rests on a factual claim about how AI or humans write — "ChatGPT emits curly quotes by default," "most writers rarely do X" — link a source for it. These claims get checked, and some turn out wrong or more nuanced than they first seem (smart quotes, for instance, are a typing-time default on macOS and in Word, not a publication-step artifact). A claim with a citation can be verified; an asserted one can't. Put the links in the PR description or inline in the rule.

Style guides and licensing

The rules from the #88 license audit, recorded here so nobody has to rediscover them:

• This repo bundles no style guide it cannot verify the license for. The --style layer is config-driven; users supply their own conventions.
• Openly-licensed guides may ship later as example configs (Google, Microsoft, GOV.UK, and 18F qualify), using Vale's attribution pattern: disclaim endorsement, name the license, link the guide upstream.
• Paywalled guides (CMOS, APA, MLA, AP) are never shipped, in any form, under any name. Passing one to --style falls through to the fallback that claims no compliance. The reason is trademark and verifiability, not maintenance burden.

Run the tests

npm test

This runs the engine fixtures and the CATEGORIES.md contract checks: every detector type must be documented, every documented type must be real, and every prose statement of the engine type total must match the code. All must pass. No dependencies to install; Node 18+ only.

Documentation drift

The SSOT / ssot CI job checks repository-local Node requirements using .ssot-local.yaml on every PR. package.json owns the detector's Node minimum; README and contributor instructions carry checked copies. Existing generated skill, version, and pattern-count checks keep their own ownership.

The separate .ssot.yaml and promo-drift workflow track cross-repo promotional counts on release and schedule. Both workflows pin the checker revision; the local PR check needs no sibling repositories or private credentials.

Registered drift, missing copies, and malformed manifests fail CI. Fix the claim and its copies, and explain any change to canonical ownership or removed locators. Do not remove checks merely to make a failure disappear.

Discovery is advisory and scans prose, not every source format or value. The Node minimum needs its explicit locators. Historical releases, example corpora, and generated bundles are excluded from discovery. The initial remaining warnings are fictional funding/percentage examples and repeated editing-budget guidance. Inspect a warning before registering a fact or excluding a path; explicitly registered copies remain checked even in excluded files.

To reproduce CI, check out the checker revision pinned in .github/workflows/ssot.yml into a sibling ssot-check directory, then run:

python3 ../ssot-check/ssot_check.py check --manifest .ssot-local.yaml
python3 ../ssot-check/ssot_check.py discover --manifest .ssot-local.yaml --untracked-only --github-annotations
python3 scripts/check-ssot-controls.py ../ssot-check/ssot_check.py

The controls mutate disposable copies and verify drift, restoration, missing locations/manifests, and invalid manifests. They also prove that history can be excluded while a new unregistered current copy still warns without failing check. Record useful findings, repeated warnings, and maintenance effort in the pilot PR or a follow-up issue before expanding coverage.

Write clean prose

This repo polices writing quality, so the prose you add has to clear the same bar. Run your additions through the skill itself. Keep rule bullets terse and lead with the directive — match the length and tone of the bullets already in SKILL.md. Drop intensifiers like "strong" or "powerful"; let the rule stand on its own.

Changelog and versioning

Add an entry to CHANGELOG.md under a dated, versioned heading (## [X.Y.Z] — YYYY-MM-DD), matching the existing entries. A new rule is a minor version bump; update the version: field in the SKILL.md frontmatter to match.

After changing either canonical file, run bash scripts/sync-plugin-skill.sh && bash scripts/sync-cursor-rules.sh. This regenerates both bundles, SKILL.full.md, and the portable paste/Cursor artifacts; CI checks parity. Do not edit generated copies.