content: line-edit machine-generated writing patterns from markdown

[arivictor]

A line-editing pass over the markdown content to strip machine-generated writing tells while changing as little as possible — repair, not rewrite. A continuation of the earlier content/remove-generation-tells work, at the sentence level.

Approach

Triaged every .md file with per-defect greps, then read and edited only where a listed defect actually appeared. Files with no defect were left untouched on purpose. The single strongest deliberate use of each pattern was preserved as voice — only repetition was treated as the defect.

33 edits across 18 files; net −2 lines (nothing got longer).

What changed, by category

• Dedup — index.md stated the "trade-off / situation that earns it / over-engineering" triplet twice; wrong-abstraction.md said "DRY is about knowledge, not lines" three times; dns.md made the "map exposes the extension point" point in two adjacent paragraphs.
• Contrastive-negation tic (the main one) — the philosophy essays leaned on "isn't X — it's Y" repeatedly. Kept the one strongest instance per file (e.g. listen-to-the-tests keeps the [!IMPORTANT] callout "the problem is the design, not the test"; disagree-with-reason keeps "'I don't like it' is not a reason; it's the absence of one") and flattened the rest to positive declaratives.
• Comma-splice lists — change-you-can-see.md had two lists jammed mid-sentence → em-dashes / "and".
• Hedge repetition — mvc.md repeated "usually" three times in one paragraph.
• Rule-of-three flourish — no-pattern.md "diligence, planning ahead, leaving room, avoiding corners" → trimmed.
• Performed transitions — cut throat-clearing in shipping.md and structure.md.
• Generic example — modular-monolith.md foo/internal/ → billing/internal/, matching the page's own domain.

Left untouched on purpose

The ~75 pattern reference pages and most course modules. Their "X, not Y" constructions are technical/definitional (contract, not concrete type; has-a, not is-a), their hedges are genuine conditional caveats, and their triples are informative — none are the machine tic.

Not addressed (out of scope — flagging for a separate fix)

• drafts/blog/index.md frontmatter key is orer:, should be order: (likely breaks that page's ordering).
• content/philosophy/change-you-can-see.md has two stray double-spaces ("This is an", "which is the").

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR performs a light line-edit pass across site/course Markdown content to remove repeated “machine-generated” phrasing patterns (e.g., contrastive negations, throat-clearing transitions, repetitive hedges) while keeping edits minimal and preserving intended voice.

Changes:

• Flattens repeated “not X, but Y” constructions into more direct declarative sentences across philosophy/course modules.
• Deduplicates repeated points in a few essays and trims over-ornate rule-of-three flourishes.
• Tweaks examples/wording for consistency and readability in several pattern/course pages.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
drafts/courses/build-a-cli/testing.md	Refines explanation of test seams to remove contrastive-negation phrasing.
drafts/courses/build-a-cli/structure.md	Removes a transition sentence to make the section more direct.
drafts/courses/build-a-cli/shipping.md	Cuts throat-clearing module-intro sentence before build instructions.
drafts/courses/build-a-cli/probe.md	Rephrases Strategy-pattern mention to a simpler declarative sentence.
drafts/courses/build-a-cli/middleware.md	Tightens the “shared code belongs in neither command” rule explanation.
drafts/courses/build-a-cli/dns.md	Removes a duplicated “extension point visibility” sentence (keeps discussion later).
drafts/blog/generics.md	Tightens generics guidance wording (“start from concrete code”).
content/philosophy/wrong-abstraction.md	Deduplicates DRY/knowledge emphasis and trims repeated phrasing.
content/philosophy/no-pattern.md	Trims rule-of-three flourish and tightens a few explanatory sentences.
content/philosophy/name-the-trade-off.md	Removes extra clause to reduce repeated contrast framing.
content/philosophy/listen-to-the-tests.md	Reduces repeated negation framing and simplifies a few sentences.
content/philosophy/index.md	Tightens intro copy by removing repeated “rulebook/checklist” framing.
content/philosophy/disagree-with-reason.md	Tightens the “permission” section and removes repeated thesis restatement.
content/philosophy/change-you-can-see.md	Fixes a mid-sentence list and trims a transition clause.
content/philosophy/architecture-is-a-philosophy.md	Removes repeated framing clauses for more direct statements.
content/patterns/architectural/mvc.md	Replaces repeated hedges (“usually”) with more direct phrasing.
content/patterns/architectural/modular-monolith.md	Updates a generic internal/ example path to match the page’s domain framing.
content/index.md	Deduplicates repeated “trade-off / earns it / over-engineering” triplet.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.