From c83dd366bb61a056be055a9d7e610469531e2ded Mon Sep 17 00:00:00 2001 From: Dotta Date: Thu, 9 Jul 2026 13:51:19 +0000 Subject: [PATCH] docs(skills): apply reflection sweep guidance Adds review-bot gate guidance to the bundled GitHub PR workflow skill and documents Paperclip API authorization boundary handling in the Paperclip coordination skill. Refreshes the generated skills catalog metadata for the updated bundled skill. Co-Authored-By: Paperclip --- .../github-pr-workflow/SKILL.md | 22 ++++++++++++ .../skills-catalog/generated/catalog.json | 8 ++--- skills/paperclip/SKILL.md | 34 +++++++++++++++++++ 3 files changed, 60 insertions(+), 4 deletions(-) diff --git a/packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md b/packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md index 6ce844f1b0a..46836ea7dc8 100644 --- a/packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md +++ b/packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md @@ -70,6 +70,24 @@ Skip the `Risk and rollback` section only for clearly trivial PRs (typos, docs). - For migrations, include a dry-run plan and reversal steps. - For performance changes, include a before/after measurement, not adjectives. +## Automated code-review bots + +Automated review bots (Greptile, Superagent, Socket, Snyk, and similar) leave +their verdicts on the PR itself rather than in the required-checks list. Treat +their signal as part of the merge gate, not commentary: + +- Before flipping a PR from draft to ready, resolve every open bot comment on + the current head. If the bot exposes a confidence score (Greptile: `x/5`), + the exit condition is the top score, not "green enough". +- If a bot posts new comments after you push, address them in the same run — + do not defer to a later heartbeat and do not wait to be asked. +- If a bot's verdict is genuinely wrong, resolve the thread with a one-sentence + rationale on the PR. Silent dismissal reads as "not addressed" to the human + reviewer. +- For long-lived split PRs (child PRs of a larger recovery/split), run this + loop on every child before handing the parent back — don't rely on the human + to fan out the ask. + ## Replying to review comments - Reply on every comment, even with just "fixed in " — silent fixes leave the reviewer guessing. @@ -80,6 +98,10 @@ Skip the `Risk and rollback` section only for clearly trivial PRs (typos, docs). ## Merge checklist - All required checks green. +- All automated code-review bots satisfied on the current head SHA (Greptile + at top confidence with zero unresolved threads, Superagent security scan + cleared, etc.). Bot signals sit outside the required-checks list and must + be checked separately. - All review comments resolved. - PR title/body still accurate (update if scope changed mid-review). - Linked issue moves to `in_review` or `done` per project convention. diff --git a/packages/skills-catalog/generated/catalog.json b/packages/skills-catalog/generated/catalog.json index c8996da2bd6..915955385f5 100644 --- a/packages/skills-catalog/generated/catalog.json +++ b/packages/skills-catalog/generated/catalog.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "packageName": "@paperclipai/skills-catalog", "packageVersion": "0.3.1", - "generatedAt": "2026-07-15T22:20:53.895Z", + "generatedAt": "2026-07-17T22:03:42.589Z", "skills": [ { "id": "paperclipai:bundled:docs:doc-maintenance", @@ -374,11 +374,11 @@ { "path": "SKILL.md", "kind": "skill", - "sizeBytes": 3970, - "sha256": "f498ec4ebb1779dea37adeb1db8a8b22316282798e35ee02e2fc5ff627d7e261" + "sizeBytes": 5176, + "sha256": "0d4bfa03d0feedfe526bd8e3af87fee022d075df366262809731c4588220b595" } ], - "contentHash": "sha256:90f278c89aa0711be150c1cd2456ca25620d02f36995b113ca9837d756a37f6c" + "contentHash": "sha256:f44303c86eed17c65772129039ebb1b24e50e631a19fa9081aeb96ca8644e1ff" }, { "id": "paperclipai:optional:browser:agent-browser", diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index 11b2107f908..52a3ad69141 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -450,6 +450,40 @@ PUT /api/issues/{issueId}/documents/plan If `plan` already exists, fetch the current document first and send its latest `baseRevisionId` when you update it. +## Authorization boundaries — check ownership before mutating another agent's issue + +Paperclip evaluates `issue:read`, `issue:comment`, and `issue:mutate` +separately. Local task-bridge credentials are run-scoped, so access that was +valid from one checked-out issue may not be valid from another run. A mention +grant can allow reading and commenting on another agent's issue, but it does +not grant mutation access. A successful `GET` therefore does not prove that a +later `PATCH` is authorized. + +If a write falls outside the active boundary, the API returns +`403 Issue is outside this actor's authorization boundary` and drops it. Do +not retry the same mutation with a different verb or from an unrelated run. + +**Before writing to another issue:** + +1. Fetch the issue and inspect `assigneeAgentId`, then confirm that the current + wake, assignment, mention, linked-issue context, or delegated child task + explicitly gives this run the required action. The issue response does not + expose an `authorizationBoundary` field, so do not infer mutation access + from read access alone. +2. If the run has read/comment access only, route the requested mutation via: + - A comment on your own issue naming the target owner and the desired change. + - A child issue assigned to the owner with the mutation encoded as its body. + - An `interactions` request on your issue when a human/board approval is + the correct escalation. + +**Do not** treat the 403 as a signal to retry with a different verb — the +boundary is real. Retrying wastes the heartbeat and leaves the mutation +un-owned. + +This applies especially to coordinator roles (CTO, plan owners, routine +owners) that regularly need to clear blockers on issues held by engineers, +QA, or CloudOps. + ## Key Endpoints (Hot Routes) | Action | Endpoint |