From ca0e60e009d282b957847f24a9bf393420fbad2f Mon Sep 17 00:00:00 2001
From: Devin Foley <devin@paperclip.ing>
Date: Mon, 22 Jun 2026 12:31:36 -0700
Subject: [PATCH] fix: align linked-issue PR guidance

Keep commitperclip guidance in contributor-facing PR docs and bot copy instead of root AGENTS.md or bundled product skills.

Align the accepted examples with the current linked-issue checker, including Resolves and the inline-description field threshold.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 .github/PULL_REQUEST_TEMPLATE.md                    | 13 ++++++++-----
 .github/scripts/check-pr-linked-issue.mjs           |  2 +-
 .../scripts/tests/check-pr-linked-issue.test.mjs    |  1 +
 CONTRIBUTING.md                                     |  6 +++---
 4 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index a2ef5aa0a35..5d3aa2da0e1 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -19,8 +19,10 @@
 <!--
   Required. Pick ONE of the following two paths:
 
-  (A) Issue exists — tag each linked issue with `Fixes: #123`, `Closes #123`,
-      or `Refs #123`. Include duplicates and closely related issues too.
+  (A) Issue exists — tag each linked issue with `Fixes #123`, `Closes #123`,
+      `Resolves #123`, or `Refs #123`. A bare `#123` also counts, but use an
+      explicit keyword when it describes the relationship. Include duplicates
+      and closely related issues too.
 
   Only reference PUBLIC GitHub issues/PRs here. Do NOT paste internal,
   instance-local Paperclip references — ticket ids like PAPA-123 / PAP-224,
@@ -28,8 +30,9 @@
   contributors cannot open them. See CONTRIBUTING.md → "No Internal Issue
   References".
 
-  (B) No issue exists — describe the underlying problem here, following the
-      relevant issue template so reviewers get the same fields:
+  (B) No issue exists — describe the underlying problem here with at least
+      three headings or labels from the relevant issue template so reviewers
+      get the same fields:
         • Bug:     .github/ISSUE_TEMPLATE/bug_report.yml
         • Feature: .github/ISSUE_TEMPLATE/feature_request.yml
         • Adapter: .github/ISSUE_TEMPLATE/adapter_request.yml
@@ -86,7 +89,7 @@
 - [ ] I have specified the model used (with version and capability details)
 - [ ] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
 - [ ] I have searched GitHub for duplicate or related PRs and linked them above
-- [ ] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template
+- [ ] I have either (a) linked existing issues with `Fixes #` / `Closes #` / `Resolves #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template
 - [ ] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs)
 - [ ] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details
 - [ ] I have run tests locally and they pass
diff --git a/.github/scripts/check-pr-linked-issue.mjs b/.github/scripts/check-pr-linked-issue.mjs
index 46f3a881e90..2184df0255c 100644
--- a/.github/scripts/check-pr-linked-issue.mjs
+++ b/.github/scripts/check-pr-linked-issue.mjs
@@ -106,7 +106,7 @@ export function checkLinkedIssue(body, prTitle = '') {
     passed,
     failures: passed ? [] : [
       'No linked issue or inline issue description found — either tag an existing issue ' +
-      'with `Fixes #NNN` / `Closes #NNN` / `Refs #NNN`, or describe the underlying issue ' +
+      'with `Fixes #NNN` / `Closes #NNN` / `Resolves #NNN` / `Refs #NNN`, or describe the underlying issue ' +
       'inline in the PR body following one of our issue templates ' +
       '(https://github.com/paperclipai/paperclip/tree/master/.github/ISSUE_TEMPLATE). ' +
       'See CONTRIBUTING.md → "Link Issues or Describe Them In-PR".',
diff --git a/.github/scripts/tests/check-pr-linked-issue.test.mjs b/.github/scripts/tests/check-pr-linked-issue.test.mjs
index 4f6d1a63e16..1c017dad638 100644
--- a/.github/scripts/tests/check-pr-linked-issue.test.mjs
+++ b/.github/scripts/tests/check-pr-linked-issue.test.mjs
@@ -52,6 +52,7 @@ test('fails with no issue reference when no skip prefix', () => {
   const result = checkLinkedIssue('Added a cool feature, no issue linked', 'feat: something');
   assert.equal(result.passed, false);
   assert.ok(result.failures[0].includes('Fixes #NNN'));
+  assert.ok(result.failures[0].includes('Resolves #NNN'));
 });
 
 test('fails with cross-repo issue reference', () => {
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 10849c754c6..1aab584b4c1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -54,8 +54,8 @@ Every pull request **must** follow the PR template at [`.github/PULL_REQUEST_TEM
 
 We do not gate PRs on a pre-existing issue. Two acceptable paths:
 
-1. **Issue exists** — search the [Issues database](https://github.com/paperclipai/paperclip/issues) for anything this PR addresses and tag each one with `Fixes: #123` / `Closes #123` / `Refs #123` so GitHub auto-links them. If there are **duplicate or closely related issues**, link all of them, not just the one you picked. If there are **related PRs** (prior attempts, dependent work, follow-ups, abandoned predecessors), link those too.
-2. **No issue exists** — describe the problem directly in your PR body, following one of our [issue templates](.github/ISSUE_TEMPLATE/) so a reviewer has the same fields they'd get from a filed issue:
+1. **Issue exists** — search the [Issues database](https://github.com/paperclipai/paperclip/issues) for anything this PR addresses and tag each one with `Fixes #123` / `Closes #123` / `Resolves #123` / `Refs #123` so GitHub auto-links them. A bare `#123` also counts, but use an explicit keyword when it describes the relationship. If there are **duplicate or closely related issues**, link all of them, not just the one you picked. If there are **related PRs** (prior attempts, dependent work, follow-ups, abandoned predecessors), link those too.
+2. **No issue exists** — describe the problem directly in your PR body, using at least three headings or labels from one of our [issue templates](.github/ISSUE_TEMPLATE/) so a reviewer has the same fields they'd get from a filed issue:
    - **Bug fix:** what happened, expected behavior, steps to reproduce, Paperclip version/commit, deployment mode. See [`bug_report.yml`](.github/ISSUE_TEMPLATE/bug_report.yml).
    - **Feature:** problem/motivation, proposed solution, alternatives considered, roadmap alignment. See [`feature_request.yml`](.github/ISSUE_TEMPLATE/feature_request.yml).
    - **New adapter:** agent or provider, why it's useful, how it's invoked. See [`adapter_request.yml`](.github/ISSUE_TEMPLATE/adapter_request.yml).
@@ -66,7 +66,7 @@ Either way, a reviewer should be able to understand the underlying issue without
 
 Many contributors run their own Paperclip instance to manage their work. Issue ids and links from *your* instance are private — reviewers and other contributors cannot open them, so they show up as clutter or broken links.
 
-In your PR title, description, commits, and comments, **only reference public GitHub issues and PRs** — `#123`, `Fixes #123` / `Closes #123` / `Refs #123`, or full `https://github.com/paperclipai/paperclip/...` URLs.
+In your PR title, description, commits, and comments, **only reference public GitHub issues and PRs** — `#123`, `Fixes #123` / `Closes #123` / `Resolves #123` / `Refs #123`, or full `https://github.com/paperclipai/paperclip/...` URLs.
 
 Do **not** include references to internal/instance-local Paperclip work, such as: