Skip to content

Add annotated-link / definition exception to the em dash rule (#14)#190

Open
pfstr wants to merge 1 commit into
blader:mainfrom
pfstr:annotated-link-em-dash-exception
Open

Add annotated-link / definition exception to the em dash rule (#14)#190
pfstr wants to merge 1 commit into
blader:mainfrom
pfstr:annotated-link-em-dash-exception

Conversation

@pfstr

@pfstr pfstr commented Jul 22, 2026

Copy link
Copy Markdown

What

Adds an exception to pattern #14 (em/en dash hard cut) for em dashes that act as a structural separator in an annotated link or definition, rather than a mid-sentence AI tell.

The canonical case is a reference/source list:

[Debian Wiki – SSH](https://wiki.debian.org/SSH) — Debian-specific notes on SSH configuration.

Here the em dash after ](url) separates the linked title from its description. The same shape appears in glossaries and definition lists (**Term** — definition). Under the current hard cut, the skill rewrites ... ) — Debian-specific notes into ... ). Debian-specific notes, which flattens a deliberate formatting convention.

Behavior added

  • Detection: an em dash that directly follows a Markdown link ](url) (or a bolded/leading term at the start of a list item) and introduces a descriptive clause for that title.
  • Ask once: on the first such separator in a document, the skill asks the user whether to keep these separators as em dashes or convert them like any other em dash, then applies that choice to every matching separator. No per-occurrence re-prompting.
  • Embedded mode: cannot ask, so it defaults to keeping these separators (legitimate convention, not a tell).
  • The final / scan step is updated so the two standing exceptions (voice sample, kept annotated-link separators) no longer contradict the "any hit means the draft isn't done" check.

The exception is scoped narrowly: only the title/term separator is affected; em dashes anywhere else in the prose still follow the existing rule.

Maintenance contract

Per AGENTS.md, bumped the version to 2.10.0 in SKILL.md (metadata.version), .claude-plugin/plugin.json, and the README.md version history, and added a changelog note explaining the fix. No numbered patterns were added, removed, or renumbered (still 33). python3 scripts/validate-package.py passes, and SKILL.md is 425/500 lines.

Why

Reference lists that use the title — description convention are common in technical writing, and having the humanizer silently rewrite the separator is surprising. Asking once preserves author intent without weakening the default em dash cut for real prose tells.

An em dash used as the separator in a reference-list item
(`[title](url) — description`) or a definition list (`**Term** — definition`)
is a formatting convention, not a mid-sentence AI tell. The current hard cut
flattens these, e.g. turning a source list's `... ) — Debian-specific notes`
into `... ). Debian-specific notes`.

Section 14 now describes the annotated-link / definition pattern, tells the
skill to detect it, and asks the user once whether to keep or convert these
separators, then applies that choice document-wide. Embedded mode (which cannot
ask) defaults to keeping them. The closing scan step is updated so the two
exceptions (voice sample, kept annotated-link separators) no longer contradict
the "any hit means the draft isn't done" check.

Version bumped to 2.10.0 across SKILL.md, README.md, and plugin.json per the
maintenance contract. No change to the 33 patterns.
@pfstr
pfstr force-pushed the annotated-link-em-dash-exception branch from c7e4dc8 to b768c8d Compare July 22, 2026 06:33
conorbronsdon pushed a commit to conorbronsdon/avoid-ai-writing that referenced this pull request Jul 22, 2026
An em dash after a bolded lead term or markdown link opening a list item
("**Term** — description", "[label](url) — description") is typography,
not a prose splice, and no longer counts toward the 1-per-1,000-words
rate. The detector exclusion is line-anchored with an optional bullet
marker, so mid-sentence splices still count. Fixture pair added: a
definition-style feature list stays clean; the same dash density in
flowing prose still fires.

This repo's own README and changelog use the separator convention
throughout — that's the strict-context false positive in practice.
Same carve-out independently proposed upstream in blader/humanizer#190.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011MYk8KLh4KovTFwW2idcqb
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