From 71e1bc260d18a8ec00a18f3f6d2bab1b33134114 Mon Sep 17 00:00:00 2001 From: Andrew Orobator Date: Tue, 17 Mar 2026 09:35:57 -0400 Subject: [PATCH 1/3] Clarify linked ticket references in Paperclip skill Co-Authored-By: Paperclip --- skills/paperclip/SKILL.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index 0e6044e6..eb098c49 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -71,6 +71,8 @@ Read enough ancestor/comment context to understand _why_ the task exists and wha **Step 8 — Update status and communicate.** Always include the run ID header. If you are blocked at any point, you MUST update the issue to `blocked` before exiting the heartbeat, with a comment that explains the blocker and who needs to act. +When writing an issue description or comment body that mentions another Paperclip ticket, always format each ticket reference as a clickable Markdown link using the company-prefixed UI path, for example `[PAP-224](/PAP/issues/PAP-224)`. + ```json PATCH /api/issues/{issueId} Headers: X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID @@ -144,12 +146,19 @@ Access control: ## Comment Style (Required) -When posting issue comments, use concise markdown with: +When posting issue comments or writing issue descriptions, use concise markdown with: - a short status line - bullets for what changed / what is blocked - links to related entities when available +**Ticket references are links (required):** If you mention another issue identifier such as `PAP-224`, `ZED-24`, or any `{PREFIX}-{NUMBER}` ticket id inside a comment body or issue description, wrap it in a Markdown link: + +- `[PAP-224](/PAP/issues/PAP-224)` +- `[ZED-24](/ZED/issues/ZED-24)` + +Never leave bare ticket ids in issue descriptions or comments when a clickable internal link can be provided. + **Company-prefixed URLs (required):** All internal links MUST include the company prefix. Derive the prefix from any issue identifier you have (e.g., `PAP-315` → prefix is `PAP`). Use this prefix in all UI links: - Issues: `//issues/` (e.g., `/PAP/issues/PAP-224`) @@ -172,6 +181,7 @@ Submitted CTO hire request and linked it for board review. - Approval: [ca6ba09d](/PAP/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b) - Pending agent: [CTO draft](/PAP/agents/cto) - Source issue: [PC-142](/PAP/issues/PC-142) +- Depends on: [PAP-224](/PAP/issues/PAP-224) ``` ## Planning (Required when planning requested) From 7a08fbd37001702b448fa3225b5308d412ab74ac Mon Sep 17 00:00:00 2001 From: Andrew Orobator Date: Tue, 17 Mar 2026 09:43:47 -0400 Subject: [PATCH 2/3] Reduce duplicate ticket-link guidance Co-Authored-By: Paperclip --- skills/paperclip/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index eb098c49..1b895f16 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -71,7 +71,7 @@ Read enough ancestor/comment context to understand _why_ the task exists and wha **Step 8 — Update status and communicate.** Always include the run ID header. If you are blocked at any point, you MUST update the issue to `blocked` before exiting the heartbeat, with a comment that explains the blocker and who needs to act. -When writing an issue description or comment body that mentions another Paperclip ticket, always format each ticket reference as a clickable Markdown link using the company-prefixed UI path, for example `[PAP-224](/PAP/issues/PAP-224)`. +When writing issue descriptions or comments, follow the ticket-linking rule in **Comment Style** below. ```json PATCH /api/issues/{issueId} From c539fcde8b73fe7abb52ac48556dfdcf665373a1 Mon Sep 17 00:00:00 2001 From: Andrew Orobator Date: Tue, 17 Mar 2026 09:52:32 -0400 Subject: [PATCH 3/3] Fix stale Paperclip issue link example Co-Authored-By: Paperclip --- skills/paperclip/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index 1b895f16..054c6a87 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -180,7 +180,7 @@ Submitted CTO hire request and linked it for board review. - Approval: [ca6ba09d](/PAP/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b) - Pending agent: [CTO draft](/PAP/agents/cto) -- Source issue: [PC-142](/PAP/issues/PC-142) +- Source issue: [PAP-142](/PAP/issues/PAP-142) - Depends on: [PAP-224](/PAP/issues/PAP-224) ```