Backtick-escape #N references to prevent phantom GitHub auto-links in skill docs

Context

Surfaced by @tobiu on 2026-04-24. GitHub's markdown renderer auto-links any bare #N token (e.g., #4) to the Nth-ever issue in the repository. This creates phantom cross-references in two places:

1. Native Edge Graph ingestion. The Retrospective daemon and FileSystemIngestor.syncWorkspaceToGraph parse issue/PR/discussion bodies and comments for #N patterns as RELATES_TO / MENTIONS edges. Bare #N in descriptive prose creates edges that don't correspond to actual architectural relationships.
2. GitHub's own "mentioned in" index on each referenced issue. Every descriptive #N in a ticket body adds noise to the referenced issue's "linked from" section, diluting the signal from intentional references (Resolves, BLOCKED_BY, etc.).

Empirical observation: the 2026-04-24 session filed 11+ tickets by @neo-opus-ada + 3 by @neo-gemini-pro, each citing prior tickets in descriptive prose. A non-trivial fraction of the session's Native Edge Graph growth is phantom edges from bare #N references that were meant descriptively, not structurally.

The Problem

Markdown authors need a way to distinguish:

• Structural references (the reference IS the graph edge) — Resolves #N, BLOCKED_BY #N, conventional-commit feat(scope): ... (#N), update_issue_relationship payloads
• Descriptive references (talking about the number without asserting a graph relationship) — "see #N for context," "mirrors the pattern from #N," "filed alongside #N"

GitHub doesn't distinguish these by intent — it auto-links all bare #N. The convention agents need is backtick-escape for descriptive references: `#N` renders as #N in monospace without auto-linking.

The Architectural Reality

Impact surfaces:

• .agent/skills/ticket-create/references/ticket-create-workflow.md §5 Fat Ticket Body Structure — example ticket bodies include many bare #N references in "Related" sections. Prose references should be backticked.
• .agent/skills/pr-review/references/pr-review-guide.md §4 Graph Ingestion Tags — [KB_GAP] / [TOOLING_GAP] / [RETROSPECTIVE] tag body text frequently references other tickets. These are annotations, not structural edges — should be backticked.
• .agent/skills/pull-request/references/pull-request-workflow.md §3 Commit Sequence — already correctly uses (#TICKET_ID) bare in commit subjects (those ARE intentional edges). Prose examples elsewhere in the workflow need auditing.
• .agent/skills/ideation-sandbox/references/ideation-sandbox-workflow.md — canonical case studies (#10119, #10137) referenced descriptively. Body examples should demonstrate the backtick convention.

No source-code or MCP-tool changes required. Pure doc-convention work.

The Fix

Add a concise subsection to the canonical authoring skills (ticket-create, pr-review, pull-request, ideation-sandbox) covering the distinction + correct form:

NEO_CODE_BLOCK_0

Update inline examples across the four skill reference files so agents learn the convention from the canonical artifacts.

Acceptance Criteria

• .agent/skills/ticket-create/references/ticket-create-workflow.md gains a "Reference Hygiene" subsection with the above convention.
• .agent/skills/pr-review/references/pr-review-guide.md gains the symmetric subsection — with specific call-out that [KB_GAP] / [TOOLING_GAP] / [RETROSPECTIVE] tag bodies should use backtick-escape.
• .agent/skills/pull-request/references/pull-request-workflow.md gains the symmetric subsection — explicitly confirming that conventional-commit (#N) stays bare (those ARE intentional edges).
• .agent/skills/ideation-sandbox/references/ideation-sandbox-workflow.md gains the symmetric subsection — canonical case studies in inline examples demonstrate the backtick form.
• Inline example references in each skill file use backticks for descriptive mentions. Structural references stay bare.
• Post-merge empirical: next 5 agent-authored tickets/PRs/Discussions observe the convention in descriptive sections, without triggering unintended phantom edges on referenced tickets.

Out of Scope

• Retroactive cleanup of existing tickets / PRs / Discussions. Not feasible (would require editing dozens of agent-authored artifacts). Going forward only. Phantom edges from past sessions stay as archaeological noise.
• Automated enforcement (CI linter, pre-commit hook). Policy-level first; technical enforcement only if compliance drift appears.
• GitHub's @-mention equivalent (@user vs `@user`). Same pattern exists for user mentions but different failure mode — if escalation wanted, separate ticket.

Avoided Traps

• "Backtick everything": rejected. Conventional-commit subjects and Resolves #N keywords MUST stay bare — those rely on GitHub's auto-link/auto-close magic. Over-escaping breaks intentional behavior.
• "Only backtick in certain skill files": rejected as inconsistent. The convention applies wherever agents author markdown that renders through GitHub's parser — all authoring skills.
• "Use HTML <code> tags instead of backticks": rejected as heavier-weight. Backticks are the markdown-native escape; HTML tags render identically but require more typing + are less common.

Related

• Origin: @tobiu 2026-04-24 observation on phantom auto-link pollution
• Session memory: 11+ tickets authored by @neo-opus-ada this session contained bare #N references in prose — empirical evidence of the pattern's prevalence
• Sibling conventions: ticket-create §9 Anti-Patterns (title-prefix duplication) and pull-request §3.1 (feat vs chore discipline) already codify similar authoring-layer conventions
• Adjacent skill-authoring work this session: #10272 (comment-ID propagation), #10276 (ideation adjacency sweep), #10278 (iterative review workflow), #10281 (Progressive Disclosure refactor)

Origin Session ID: b02bd06c-a2cb-4aff-8af1-c4f2643c91be

Retrieval Hint: "backtick-escape #N reference auto-link phantom graph edge descriptive vs structural"