Repository navigation
Upgrade kept issue-reference comments to explicit hyperlinks (// see <url>) #573
Copy link
Copy link
Closed
Labels
area:documentationUpdates to documentationUpdates to documentationtype:enhancementNew feature or requestNew feature or request
Description
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
#526isn'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 withgit 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#NNNis not "linking." - Drop bare origin/closing-issue citations. State that a trailing
#NNNmerely 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 /
describetitles 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/
describetitles.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
area:documentationUpdates to documentationUpdates to documentationtype:enhancementNew feature or requestNew feature or request
Activity
chore: drop bare origin-issue citations from comments and test titles
chore: drop bare origin-issue citations from comments and test titles (…
docs(agents): slim AGENTS.md to non-derivable context; move test-titl…
docs(agents): slim AGENTS.md to non-derivable context; move test-titl…
goosewobbler commentedon Jul 20, 2026
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:
shouldconvention → now avitest/valid-titleeslint rule (docs(agents): slim AGENTS.md to non-derivable context; move guidance into tooling #598).#NNNin comments → a custom eslint rule oversourceCode.getAllComments().#NNNin test titles →vitest/valid-titlemustNotMatch: #\d+, after cleaning the ~10 existing title refs (#463 review,#558,#520).Net: the intent of this issue (make kept refs actionable / drop noise) survives, but as lint + cleanup, not AGENTS.md prose.
chore(lint): enforce comment + test-title issue-ref conventions in es…
chore(573): sweep bare issue refs from source comments; enforce with …
chore: sweep bare issue refs from source comments; enforce in eslint (#…
docs(agents): slim AGENTS.md to non-derivable context; move guidance …