Skip to content

Upgrade kept issue-reference comments to explicit hyperlinks (// see <url>) #573

Closed

Description

@goosewobbler

Follow-up to the origin-issue-citation cleanup (which removes bare trailing #NNN tags from self-sufficient comments and test titles).

Rationale

The cleanup deliberately keeps issue refs that carry weight — load-bearing tracking refs ("until #X", "remove when #X"), (#NNN review) provenance, and cross-file "decision-shorthand" refs (e.g. #372 = strictReachable-abort). But most of those are still bare numbers, which have low value in the reading context:

  • Humans: a bare #526 isn't clickable in a comment or in test output — using it means manually going to GitHub and typing the number. In-source it's also largely redundant with git blame → PR → issue.
  • LLMs: a bare number is only useful as a cross-reference join key and is largely redundant with git history; it's actionable only with issue-fetch tooling.

Where a ref is worth keeping, it's worth making actionable — an explicit hyperlink a reader (or agent) can follow directly.

Scope — codify the convention in AGENTS.md

Update the ### Comments subsection (under Coding Standards in AGENTS.md) so the rules match what the cleanup established. Concretely:

  • Kept issue/PR refs must be explicit hyperlinks, not bare numbers. Replace the current "Do link load-bearing tracking refs — an issue or PR whose resolution removes or rewrites the commented code" with guidance that such a ref is written as a full URL, e.g. // …rationale. See https://github.com/goosewobbler/releasekit/issues/526 — a bare #NNN is not "linking."
  • Drop bare origin/closing-issue citations. State that a trailing #NNN merely tagging the issue a piece of code closed/implemented — where the comment already stands on its own — should be omitted (git history is the canonical trace). This is the rule the cleanup applied.
  • Test / describe titles carry no issue refs. A title string can't be a hyperlink, so titles stay pure behavior specs; traceability lives in git, not the title.
  • Reconcile the existing "Keep the rationale, drop the citation" line so "citation" clearly covers bare issue numbers, not just drifting details (versions, stack traces).

Scope — the codebase

  • Audit the ~140+ deliberately-kept issue refs in comments and, for those that genuinely aid understanding, convert to the linked form above; drop any that add nothing once they'd need a full URL.
  • Consider a lightweight lint/check so future refs follow the linked form from the start.

Non-goals

  • Not re-litigating the bare-tag removals from the cleanup PR.
  • Not adding links to test/describe titles.

Activity

  1. modified the milestone: 0.42.0 on Jul 19, 2026
  2. goosewobbler commented on Jul 20, 2026

    @goosewobbler
    OwnerAuthor

    Approach update. PR #598 pivoted from codifying the comment-ref convention in AGENTS.md to slimming AGENTS.md and moving conventions into deterministic tooling (comprehensive context files hurt agent performance — keep only the non-derivable, push the rest into lint/CI). So the "codify in AGENTS.md" scope of this issue is intentionally being dropped: prose rules are being removed, not expanded.

    What that leaves for this issue, reframed as deterministic enforcement + cleanup rather than docs:

    • ✅ Test-title should convention → now a vitest/valid-title eslint rule (docs(agents): slim AGENTS.md to non-derivable context; move guidance into tooling #598).
    • ⬜ Bare #NNN in comments → a custom eslint rule over sourceCode.getAllComments().
    • ⬜ Bare #NNN in test titles → vitest/valid-title mustNotMatch: #\d+, after cleaning the ~10 existing title refs (#463 review, #558, #520).
    • ⬜ Codebase sweep of the ~260 in-source refs (convert load-bearing ones to full URLs; drop the rest).

    Net: the intent of this issue (make kept refs actionable / drop noise) survives, but as lint + cleanup, not AGENTS.md prose.

  3. removed this from the 0.41.1 milestone on Jul 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions