feat(rules): add response-links-summary output convention

[dylanschmittle-uniswap]

Adds .claude/rules/response-links-summary.md — an always-on output convention: when stopping (not asking, not mid-task), end the response with a trailing ## Links block (grouped by type, full clickable URLs, omitted when empty), and link any referenced component by URL rather than a bare ID.

Why a rule (not a skill)

This is a passive output convention with no trigger phrase — it should apply to every stopping turn, so it belongs in .claude/rules/ alongside linting.md/plugin-docs.md, not as a task-invoked skill. (A Stop hook could enforce it programmatically, but a hook can't author the links — guidance is the right fit, matching how it already lives as personal memory.)

Generalized from personal memory

Stripped the Uniswap/Datadog-US1 and individual-name specifics; kept the portable convention (PRs / tickets / observability / docs categories, full URLs, no bare IDs).

Draft for review — happy to adjust categories/wording or convert to a hook if you'd prefer enforcement.

AI-Generated Description

What

Adds .claude/rules/response-links-summary.md — an always-on output convention: when stopping (not asking, not mid-task), end the response with a trailing ## Links block (grouped by type, full clickable URLs, omitted when empty), and link any referenced component by URL rather than a bare ID.
Single new file under .claude/rules/; no code or behavior changes elsewhere.

Why

Readers act on these links immediately — open the PR, check the live dashboard, read the ticket. A trailing, grouped, fully-linked index turns "scroll back and reconstruct what was touched" into one glance, and avoids the common failure of citing a bare ID (#1234, monitor name, dashboard slug) that the reader then has to hunt down.

Why a rule (not a skill)

This is a passive output convention with no trigger phrase — it should apply to every stopping turn, so it belongs in .claude/rules/ alongside linting.md / plugin-docs.md, not as a task-invoked skill. (A Stop hook could enforce it programmatically, but a hook can't author the links — guidance is the right fit, matching how it already lives as personal memory.)

Generalized from personal memory

Stripped the Uniswap/Datadog-US1 and individual-name specifics; kept the portable convention (PRs / tickets / observability / docs categories, full URLs, no bare IDs).

Changes

File	Change
.claude/rules/response-links-summary.md	New rule (+31 lines): when/what to include in a trailing ## Links block, full-URL requirement, "skip the section entirely if empty" guidance
Total diff: +31 / -0 across 1 file. Docs-only; no plugin code touched, so no packages/plugins/ version bump required.

Test plan

• Markdown renders correctly under .claude/rules/
• markdownlint-cli2 clean on the new file
• Future stopping turns end with a ## Links block when there are actionable links, and omit it entirely when there are none
  Draft for review — happy to adjust categories/wording or convert to a hook if you'd prefer enforcement.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ai-toolkit-slack-oauth-backend	Ready	Preview, Comment	Jun 22, 2026 4:13pm

[github-actions]

📚 Documentation Check ✅

Verdict: Passed

No plugin files were modified, so no version bump is required. The change adds a new Claude Code rules file with no breaking changes. fail_on_missing_docs is false, so informational suggestions do not block the PR.

---

PR #537 Documentation Check

Change summary: This PR adds a single new file .claude/rules/response-links-summary.md that instructs Claude Code to append a ## Links block at the end of stopping turns.

Checks

Check	Status	Notes
Plugin version bump	✅ Not required	No files under packages/plugins/ were modified
CLAUDE.md update	ℹ️ Optional	Root CLAUDE.md does not enumerate individual rule files; no update strictly required
README.md update	✅ Not required	No package structure, API, or usage patterns changed
Changelog entry	ℹ️ Informational	New behavior rule added — a changelog note would be helpful but is not blocking

Verdict: PASS — no blocking issues found.

Missing Updates

Type	File	Severity	Reason
📝 changelog	CHANGELOG.md	ℹ️ info	A new Claude Code output convention (response-links-summary) was introduced. A changelog entry would help track behavioral changes over time.

✨ No Documentation Updates Needed

All documentation appears to be up to date with the code changes.

---

_{🤖 Generated by Claude Documentation Validator | Mode: suggest}

[github-actions]

🤖 Claude Code Review

✅ Review complete

Review Summary

This PR adds a single new documentation file .claude/rules/response-links-summary.md that defines a convention for Claude Code: when finishing a stopping turn, end with a trailing ## Links block indexing all actionable URLs from the turn.

What I checked

• File scope: Single new markdown rule file, no code changes
• Conflict with existing rules: The other rules in .claude/rules/ (plugin-docs.md, linting.md) operate in different domains; no overlap or contradiction
• Internal consistency: The rule is self-consistent — it covers the empty case ("skip the section entirely" when no links), specifies grouping behavior, and clarifies that the block sits below the substantive response
• CLAUDE.md alignment: This is a documentation-only change, not a packages/plugins/ change, so the mandatory plugin version-bump rule does not apply

Observations (non-blocking)

• The "stopping turn" definition relies on Claude correctly distinguishing between mid-task, awaiting-input, and final responses. That judgment is implicit; in practice many turns will legitimately have zero links, and the "skip entirely" guidance handles that cleanly.
• The rule is prescriptive about format (## Links heading, grouped by type) but doesn't show a worked example. An example would make the contract concrete, but the prose is clear enough that this is a nice-to-have, not a gap.

Verdict

No bugs, security issues, or correctness problems. Documentation-only addition with a clear rationale section.

Links

• PR: feat(rules): add response-links-summary output convention #537

---

_{💡 Want a fresh review? Add a comment containing @request-claude-review to trigger a new review at any time.}

[github-actions]

📋 Review verdict: APPROVE

👆 The main review comment above is the source of truth for this PR review. It is automatically updated on each review cycle, so always refer to it for the most current feedback.

This formal review submission is for the verdict only.