Record the CommonMark code-span backtick-delimiter gotcha

[dem-ucdh]

Post-merge UMS top-up from ai-config#1104's own review lifecycle: recording the accepted round-2 finding as a reusable authoring lesson (it is not one of #1104's four recorded lessons — it surfaced from #1104's review).

The lesson

A literal backtick inside a Markdown inline code span needs a longer delimiter, not a backslash. Per CommonMark's code-span rule, backslash escapes are not processed inside code spans and delimiter matching is purely lexical, so a single-backtick span wrapping backtick-bearing text closes at the first inner backtick and renders as garbled fragments.

Why it earns an entry rather than being a one-off (per learn-from-review-findings):

• It is a recurring authoring trap with a definite rule (widen the delimiter), not a typo.
• No content check catches it — it is well-formed Markdown, so markdownlint, the semantic-line-break check, and validate all passed on Record four lessons from ai-config#1042's review lifecycle #1104; only the reviewer (or a rendered-blob fetch) saw the garble. That is the same blind spot as the MD010-in-fences gotcha the new section sits beside.

Change

One new ## section in memories/tools.md, beside the existing markdownlint gotchas. Hand-written prose, +39 lines, no generated trees. The entry's own example code spans were checked to render correctly (the double-backtick span at the case record wraps a single-backtick-bearing string with no adjacent-backtick run inside it).

Verification

• Branched off origin/main; push verified against git ls-remote (matches HEAD, 1 commit ahead).
• Banned-punctuation scan over origin/main...HEAD: 0 non-ASCII on added lines.
• Multi-sentence-line scan over the 39 added lines: 0 flagged.

🤖 Generated with Claude Code

https://claude.ai/code/session_015icfsSybE9vMSt8cUrXB6X

---

Generated by Claude Code

[github-actions]

Claude finished review — View run

---

Code Review Summary — #1106

PR: "Record the CommonMark code-span backtick-delimiter gotcha" — a single-file addition to memories/tools.md (+39/-0), documenting a Markdown authoring lesson learned during PR #1104's review.

Verification performed

• Gating check: PR is open, not draft, not previously commented on by claude — proceeded with review.
• Content correctness: Fetched the CommonMark spec (spec.commonmark.org/0.31.2/#code-spans) and confirmed the entry's core technical claims are accurate — backslash escapes are not processed inside code spans, and a code span closes at the first backtick-run of equal length to its opening delimiter.
• Worked example: Manually parsed the byte sequence of the new entry's own demonstration code span ( git commit -m "fix the \slast` guard"` ) against CommonMark's delimiter-matching rule. It resolves correctly — the double-backtick delimiter correctly encloses the single-backtick content with no premature closing, exactly as the entry claims.
• Citation verification (anti-hallucination):
  • PR Record four lessons from ai-config#1042's review lifecycle #1104 exists and is merged ("Record four lessons from ai-config#1042's review lifecycle") — consistent with this PR describing itself as a post-merge top-up from Record four lessons from ai-config#1042's review lifecycle #1104's review lifecycle.
  • Commit 4b30781 exists (4b307819b8...) and its real commit message matches the fix described in the new entry almost verbatim.
• Format/style checks: No banned non-ASCII punctuation (em-dash, curly quotes, etc.) in added lines; no obvious multi-sentence-per-line violations found on manual scan — consistent with the PR body's own self-reported scan results.
• Duplication check: Confirmed this is not a duplicate of the related memories/git.md entry (shell command-substitution backtick gotcha, a different mechanism) or the existing MD010-in-fences entry it sits beside.
• Structure: Follows the corpus's established Do/Don't pattern and case-record convention used throughout memories/tools.md.

No bugs, no CLAUDE.md/lab-manual violations, and no hallucinated content found. This is a pure-prose documentation change with no code/logic to assess for correctness bugs.

Note: subagent dispatch for this review failed twice with a context-length error (system prompt ~209k tokens > 200k limit) before any task-specific work began — an environment-level constraint, not specific to this PR. Given the PR's small, single-file, prose-only scope, I completed the verification directly instead of retrying subagents.

No --comment argument was provided, so no GitHub comments were posted.

Verdict

Ready for merge.

[github-actions]

💰 Cost: $5.2436 (review) — run