docs(skills): add aggregate-bound, lost-runner, and bug-class lessons to fix-failed-paperclip-run (#21745)

## 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 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-15 06:11:21 -06:00
1 parent c17ef9249d
commit 8cd2d6a73d
1 file changed
+8
@@ -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.