Skip to content

docs: strip AI prose, add STYLE.md and validateProse#134

Merged
pbakaus merged 1 commit intomainfrom
claude/improve-docs-writing-AjPMd
May 3, 2026
Merged

docs: strip AI prose, add STYLE.md and validateProse#134
pbakaus merged 1 commit intomainfrom
claude/improve-docs-writing-AjPMd

Conversation

@pbakaus
Copy link
Copy Markdown
Owner

@pbakaus pbakaus commented May 3, 2026

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


Note

Medium Risk
Moderate risk because scripts/build.js now 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.md editorial brief (principles + enforced denylist) and updates CLAUDE.md to point authors at it and document the dual content/site vs site/content editing requirement.

Replaces the build’s em-dash-only check with validateProse in scripts/build.js, expanding scan targets (including site/pages and 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.

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 pbakaus merged commit 122a82f into main May 3, 2026
3 checks passed
@pbakaus pbakaus deleted the claude/improve-docs-writing-AjPMd branch May 3, 2026 06:40
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants