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
conorbronsdon added a commit to conorbronsdon/avoid-ai-writing that referenced this pull request Jul 22, 2026
* v3.18.0: carve out definition-list separator em dashes

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

* Require the list marker in the em-dash separator carve-out

Review found the optional bullet marker excluded any line merely
starting with a bold phrase or link before the dash — including the
line-initial "**Bold lead** — full sentence" splice, which is itself
an AI tell and an evasion path for the rate rule. The marker is now
required, matching the SKILL.md prose ("list-item separator"), and
the prose spells out the boundary: only the list-item form qualifies,
mid-sentence and markerless line-initial splices still count, and the
-- substitute is never carved out.

Two boundary fixtures added: numbered-list separators stay clean
(must-not-fire) and markerless bold-lead splices still flag
(must-fire — this one fails without the regex change).

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

* Separator dashes no longer corroborate smart-punct-signature

The co-occurrence signature (curly quotes + em dash + Oxford comma +
zero typos) used bare em-dash presence for its dash leg, so a clean
definition list with separator-only dashes still completed the
signature the rate carve-out had just declared typography. The
separator regex is hoisted to a shared SEPARATOR_DASH_RE and the
signature's em-dash leg now requires a non-separator dash. Fixture:
a curly-quoted, Oxford-comma'd definition list (85 words, fired
before this change) no longer completes the signature.

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

* Cover the paren-numbered list style (1)) in the separator carve-out

Review residual: the marker alternation matched 1. but not 1), so a
paren-numbered definition list still counted toward the rate. Numbered
branch is now \d+[.)]; fixture extended with a 4) line.

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

---------

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.

1 participant