From 8cd2d6a73d2097253dd329f55b637e12b20361c6 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Sun, 15 Nov 2026 06:11:21 -0600 Subject: [PATCH] docs(skills): add aggregate-bound, lost-runner, and bug-class lessons to fix-failed-paperclip-run (#21745) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The `fix-failed-paperclip-run` skill guides agents that repair failed or stuck runs > - A recent repair series made automatic recovery more aggressive, and three lessons came out of it > - The aggregate number of automatic run starts was not bounded, so an outage produced many failing starts > - CI jobs lost to runner shutdowns and tests broken on master held merges > - Review rounds kept finding new instances of one bug class, one at a time > - This pull request adds those three lessons to the skill in eight lines > - The benefit is fewer repair rounds and safer recovery changes ## Linked Issues or Issue Description **What happened?** Recovery repairs bounded attempts per task but not the total number of automatic run starts across a company. During an outage that total was large and every start failed. CI jobs lost to runner shutdowns held merges. Review found one instance of a bug class per round. **Expected behavior** The skill tells agents to state the aggregate bound for recovery changes, to re-run lost CI jobs, and to check a whole bug class after one instance. **Steps to reproduce** 1. Read `.agents/skills/fix-failed-paperclip-run/SKILL.md` on master. 2. Observe that none of the three points is covered. Refs #21443, #21561, #21394. ## What Changed - Section 4: a repair that makes recovery start more runs states its worst-case company-wide start rate during an outage and what bounds it. - Section 6: re-run CI jobs lost to a runner shutdown; re-run an unrelated failing test once, then check master and tell its owner; after one instance of a bug class, check every entry point or counter of that class. ## Verification - `git diff --check`: no errors. - Documentation only; no code or tests changed. ## Risks Low risk. The change adds eight lines of guidance to one skill. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code, with tool use. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- .agents/skills/fix-failed-paperclip-run/SKILL.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.agents/skills/fix-failed-paperclip-run/SKILL.md b/.agents/skills/fix-failed-paperclip-run/SKILL.md index 758b156fe82..2a5517c5c9b 100644 --- a/.agents/skills/fix-failed-paperclip-run/SKILL.md +++ b/.agents/skills/fix-failed-paperclip-run/SKILL.md @@ -132,6 +132,9 @@ the evidence requires. Avoid historical string allowlists, swallowed errors, unbounded retries, or relaxing an integrity check to accommodate malformed input. Preserve the requested model, trust, isolation, and performance behavior unless a change or explicit fallback policy is part of the assignment. +A repair that makes recovery start more runs must state its worst-case starts per +hour across the company during an outage (provider refusing, crash loop, deploy) +and what bounds them; per-task caps do not bound the aggregate. Before implementation, state the behavioral rule and the strongest plausible second-order failure. Trace callers, downstream consumers, persisted state, and @@ -207,6 +210,11 @@ address review and CI failures, and inspect required checks and review on the current head SHA. Pending, skipped, and passing are distinct. Retry a failed check only with a reason; retain its evidence and fix repeatable failures. Resolve companion repository/artifact changes needed by the fix and state their ordering. +A job whose log shows the runner shut down or lost communication is lost +infrastructure: re-run it. A cancellation without that evidence may be deliberate. A test failing in a file the PR does not touch gets one re-run; if it +repeats, check master and tell the test's owner. When review finds one instance of +a bug class, enumerate and test every entry point or counter of that class before +pushing again. The PR must explain the causal defect, behavioral change, failing-before/passing- after evidence, safety regressions, actual acceptance environment, and limitations.