docs: cut AI tells from the hand-written markdown - #469
Merged
Conversation
Applies the unslop rules to the markdown this repository writes itself. The bulk is punctuation: em dashes become sentence breaks, commas, or colons, which forces several sentences carrying two ideas to become two sentences. Bold and code-span lead-ins change from "X — text" to "X. Text", the form the rules allow. Inside tables the em dash was a separator between a field and its description, so it becomes a comma. A lone em dash in a cell means "not applicable" and is data, so it stays. Two paragraphs are shared with every other repository in the organization and now read the same in all of them: the design-records pointer to osapi-io/specs, and the pull request bullet that asked for a "comprehensive description" without saying what a reviewer needs. CODE_OF_CONDUCT.md and AI_POLICY.md are untouched. The first is the Contributor Covenant, a standard text that rewording would misrepresent, and the second is byte-identical across the organization. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013oR5Gt9WPTTdPKdnShdL7L
The unslop pass reached inside fenced blocks and rewrote them as if they were prose. An aligned file tree lost its alignment and gained a leading comma; code comments were reflowed. A fenced block is code or output, not writing, so restore every one of them. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013oR5Gt9WPTTdPKdnShdL7L
retr0h
force-pushed
the
docs/unslop-markdown
branch
from
September 3, 2026 00:42
f984845 to
156b499
Compare
The earlier pass treated unslop as an em dash pass and stopped there. Running every rule over every file finds what it skipped. Headings take sentence case, except where the words are a name: "Adding a New Collector" becomes "Adding a new collector", while macOS, VMware, Apple Silicon and Max Headroom keep their capitals. Decorative emojis come off headings, which the rules ask for and the first pass left alone. "Feel free to open a Discussion" loses the chatbot opener, and reads the same in every repository. gohai is no longer "designed to be embedded", it embeds, and it uses Ohai's knowledge rather than leveraging it. Fenced blocks are left as they are throughout. A code sample or a file tree is not writing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013oR5Gt9WPTTdPKdnShdL7L
The rules ask for sentence case and the earlier passes left title case alone, so 587 headings still read "Collected Fields", "Platform Support", "Quick Start". Names keep their capitals: Claude Code, Spec Kit, macOS, Apple Silicon, Xeon, M2 Pro, Homebrew, Sonoma, VMware, Ohai, NKey, OSAPI Orchestrator, and every acronym. The word after them is the one that changes. Anchors are unaffected, since a heading anchor is lowercased already. Checked: every internal link in every repository still resolves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013oR5Gt9WPTTdPKdnShdL7L
Codecov Report✅ All modified and coverable lines are covered by tests. @@ Coverage Diff @@
## main #469 +/- ##
=======================================
Coverage 99.94% 99.94%
=======================================
Files 484 484
Lines 22877 22877
=======================================
Hits 22865 22865
Misses 12 12 Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
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
1 participant
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.
Applies the unslop rules to the markdown this repository writes itself.
osapi-io/specshad this pass in specs#105; the sister repositories never did, so the shared paragraphs had drifted apart.What changed
Mostly punctuation. Em dashes become sentence breaks, commas, or colons, which forces several sentences carrying two ideas to become two sentences.
Bold and code-span lead-ins move from
**X** — textto**X.** Text, the form the rules allow, matching what specs#105 did here.Inside tables the em dash had two different jobs, and only one is a tell:
`os.type` — runtime.GOOS value) becomes a comma.—in a cell means "not applicable". That is data, not prose, so it stays. Rewriting those would have destroyed the meaning of the gap tables.Two paragraphs are now identical across every repository
global/documentationrequires it:osapi-io/specs. Verified byte-identical across all six repositories once the component path is masked, and it also carried an em dash before.Not touched
CODE_OF_CONDUCT.mdis the Contributor Covenant, a standard text that rewording would misrepresent.AI_POLICY.mdis byte-identical across the organization, so changing it in one repository would break the same rule this PR is applying. Docusaurus content is excluded.Verification
just md-fmt-checkpasses. Every prose em dash is gone, confirmed by a scan that ignores table cells and lone-dash placeholders.🤖 Generated with Claude Code
https://claude.ai/code/session_013oR5Gt9WPTTdPKdnShdL7L