docs: strip AI prose, add STYLE.md and validateProse#134
Merged
Conversation
Site copy was being called out as AI slop (specifically the word
"load-bearing"). Five-pass cleanup with a build validator to keep it
from creeping back.
Pass 1 — mechanical purge:
- Remove "load-bearing" from impeccable.md, brand.md, live.md,
iterate-live.md
- Remove "highest-leverage" from critique.md, typeset.md, designing
- Remove em dashes from all 9 slop-page rule cards
- Replace "leverage" verb in personas.md
Pass 2 — rewrite the worst offenders:
- Changelog v2.0 "Data-driven skill rewrite" entry: drop "data-driven",
"frontier models", "collapses into monoculture", "biggest unlock",
"reflex defaults"; name the actual mechanism
- README opener: drop "deeper expertise and more control"; replace with
three concrete differentiators (7 reference files, 23 commands, 27
detection rules)
- Neo Mirai case study opener: action-first, name the image model used
Pass 3 — editorials:
- Fix negation pivot in distill.md ("simplicity is not about ... It is
about ...")
Pass 4 — homepage why-panels:
- Foundation lead: name the 7 reference files specifically
- Language lead: show the discipline mapping with real command names
- Production-codebases panel: drop "Impeccable isn't a sketchpad"
negation pivot
- Ships-code panel: replace "is native to that world" with "runs there"
Pass 5 — STYLE.md and validator:
- New STYLE.md at root: editorial brief with 12 principles and the
enforced denylist (each rule with a rationale and a suggested
replacement)
- scripts/build.js: validateNoEmDashes becomes validateProse. Adds 21
phrase rules with rationales, catches the \`--\` em-dash substitute,
expands target list to site/pages, site/content, README.md,
README.npm.md
- CLAUDE.md: replace the em-dash section with a STYLE.md pointer and
document the two-content-tree footgun (content/site/ vs site/content/
must be edited in lockstep until they're unified)
Co-authored-by: Claude <noreply@anthropic.com>
pbakaus
added a commit
that referenced
this pull request
May 3, 2026
Follow-up to #134, which scoped validateProse to user-facing copy and left the LLM-facing skill files alone. Bring those to the same bar, phased so hardening repetition stays intact. - Em dashes: 419 → 0 across SKILL.md and 35 reference files. Each replacement picks the right relationship (colon, semicolon, period, or parens) instead of letting the dash hide the choice. - Closer cleanup: deleted or rewrote the "Remember:" sermonettes that were pure adjective chants (bolder/quieter/clarify/delight/extract/ colorize/layout/typeset/audit/adapt). Survivors that load-bear an instruction now hand off to /impeccable polish instead of summarizing. - Opener taglines: rewrote the "[Verb] [object] to [outcome]" brochure openers in 12 older files to lead with the failure mode, the strongest claim, or a directive. Newer files (live, brand, product, audit, critique, harden) kept their existing openers. - data-driven: rephrased the two technical hits in live.md so the validator can stay strict on this term. - validateSkillProse: narrow validator scoped to source/skills/impeccable/. Em-dash check + the small denylist of phrases with no technical reading. Hardening repetition and structural-prose rules are deliberately not enforced — those need human judgment. Test failure on detectUrl is pre-existing (puppeteer needs --no-sandbox when running as root); unrelated to these changes. https://claude.ai/code/session_013zZY6rbB1bS8z3D63rX5hW Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Site copy was being called out as AI slop (specifically the word
"load-bearing"). Five-pass cleanup with a build validator to keep it
from creeping back.
Pass 1 — mechanical purge:
iterate-live.md
Pass 2 — rewrite the worst offenders:
"frontier models", "collapses into monoculture", "biggest unlock",
"reflex defaults"; name the actual mechanism
three concrete differentiators (7 reference files, 23 commands, 27
detection rules)
Pass 3 — editorials:
about ...")
Pass 4 — homepage why-panels:
negation pivot
Pass 5 — STYLE.md and validator:
enforced denylist (each rule with a rationale and a suggested
replacement)
phrase rules with rationales, catches the `--` em-dash substitute,
expands target list to site/pages, site/content, README.md,
README.npm.md
document the two-content-tree footgun (content/site/ vs site/content/
must be edited in lockstep until they're unified)
Co-authored-by: Claude noreply@anthropic.com
Note
Medium Risk
Moderate risk because
scripts/build.jsnow enforces new prose rules across multiple content trees/READMEs, which can fail builds unexpectedly if future copy trips the denylist.Overview
Adds a new root
STYLE.mdeditorial brief (principles + enforced denylist) and updatesCLAUDE.mdto point authors at it and document the dualcontent/sitevssite/contentediting requirement.Replaces the build’s em-dash-only check with
validateProseinscripts/build.js, expanding scan targets (includingsite/pagesand READMEs) and failing the build on em dashes,--substitutes, and a denylisted set of common AI/marketing phrases with per-rule rationales.Sweeps user-facing docs and site pages to remove/replace flagged terms (e.g.
load-bearing,highest-leverage,data-driven) and to rewrite several introductions/blurbs (README, homepage sections, case study copy, changelog entry, tutorials) to be more concrete and less template-like.Reviewed by Cursor Bugbot for commit e630d4a. Bugbot is set up for automated code reviews on this repo. Configure here.