Skip to content

Add noun-as-verb and negated-object rules to plain-writing - #258

Merged
haacked merged 5 commits into
mainfrom
haacked/plain-writing-noun-verb-ambiguity
Oct 25, 2026
Merged

haacked merged 5 commits into
mainfrom
haacked/plain-writing-noun-verb-ambiguity

Conversation

@haacked

@haacked haacked commented Oct 25, 2026 •

Copy link
Copy Markdown
Owner

Prose written with plain-writing still trips readers in two ways the skill doesn't name.

It uses a word as a verb when the code uses it as a noun. On PostHog/posthog#114053, the approvals code uses "gate" as a noun (approval_gate, "the flag write gate"). The review comments said "nothing gates targeting edits on an experiment's flag" and "the flags a rollout ungates". A reader has to reread those sentences. The Finish check "Does each sentence make sense without a second pass?" is too general to catch this.

It also negates the noun instead of the verb when "no" is on the object: "Deleting the queue changes no actions" where a person writes "Deleting the queue doesn't change any actions". The skill already bans "Nothing" or "No X" as the subject, but not as the object.

This adds a bullet to the Write Clearly section, next to the bullet about invented labels. It says not to use a word as a verb when the reader knows it as a noun from the code or domain. It also says not to stack nouns when the reader can take one of them as the sentence's verb, as in "flag approval policies". It's a separate bullet because "Keep established technical terms" lets "gates" pass the invented-labels rule. The existing negative-subject bullet now covers the object too. It keeps "no" when the sentence says what exists or what something has or lacks, as in "takes no arguments", because those read naturally.

I didn't add linter checks for either rule. A regex for noun-as-verb would mostly flag sentences that read fine, and one for "verb + no + noun" would flag natural phrases like "takes no arguments" and "returns no rows". The copy under address-pr-reviews/references/ comes from sync-portable-skills.sh.

Test plan

  • plain-writing-lint.py reports no warnings on the edited SKILL.md
  • test_plain_writing_lint.py, test-plain-writing-contract.sh, test-portable-skills.sh, and the address-pr-reviews portable skill test pass
  • sync-portable-skills.sh --check passes

https://claude.ai/code/session_01UmdWuUE96sY8TAsrLwMoq9

@haacked haacked changed the title Stop plain-writing from using code nouns as verbs Teach plain-writing two more ways AI prose misleads readers Oct 25, 2026
@haacked haacked changed the title Teach plain-writing two more ways AI prose misleads readers Add noun-as-verb and negated-object rules to plain-writing Oct 25, 2026
@haacked
haacked marked this pull request as ready for review October 25, 2026 03:42
@haacked
haacked merged commit 09162bd into main Oct 25, 2026
1 check passed
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.

1 participant