- name
SKILL.md
Файл навыка остаётся в репозитории издателя.
Вставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add paperclipai/paperclip --skill fix-failed-paperclip-run -a cursor -yВставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add paperclipai/paperclip --skill fix-failed-paperclip-run -a claude-code -yВставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add paperclipai/paperclip --skill fix-failed-paperclip-run -a codex -yВставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add paperclipai/paperclip --skill fix-failed-paperclip-run -a grok -yОтправьте скопированное сообщение в чат Grok Bot. Бот загрузит этот SKILL.md с GitHub и добавит его к навыкам, общим для всех ваших ботов.
Install this skill: https://github.com/paperclipai/paperclip/tree/HEAD/.agents/skills/fix-failed-paperclip-runОт издателя
Own the failure from evidence through a tested repair and a green PR. A diagnosis, a proposed plan, a successful provider turn, and a passing unit test are intermediate results. The finish line is a verified user workflow and a PR whose current commit passes the required checks and review.
Honor an explicit diagnosis-only request or a calling workflow's approval boundary. Otherwise proceed through implementation without a separate plan-approval pause. Carry forward existing authorization for merge, rollout, and recovery; do not ask again. When the assignment ends at a PR, distinguish local verification from deployment and recovery of the original task. This skill does not itself authorize merging or deploying.
Start from the supplied task/run URL or failure report. Resolve these facts from available tools and records before asking the user for missing information:
Use the bounded run diagnostics reference for the repository's existing run, event, log, and recovery reads.
Use authorized diagnostic access. If company scoping blocks a read, use an already-authorized diagnostic path or label the missing evidence; do not bypass the boundary.
Read repository instructions. In this repository, the code and tests under
server/src/services/heartbeat/ and server/src/services/recovery/ define
ownership, continuation, waiting, finalization, and recovery. Inspect recent changes and open/merged repairs in the
affected area. A correct fix that has not reached the target is a deployment gap;
do not create a second patch without evidence that the first is insufficient.
Choose code repair, configuration repair, or recovery from that evidence. If an
existing fix is sufficient, verify it and continue to the authorized endpoint
using its PR; do not manufacture code changes for an already-fixed defect.
Keep a compact evidence record in the working notes or driving issue: environment, revision, causal timeline, reproduction, safety assumptions, and acceptance result. Preserve useful logs and saved work before retries or cleanup. Do not put secrets or private incident links in public code, fixtures, skills, or PR descriptions.
Reconstruct the run from dispatch through preparation, provider execution, tool calls, result persistence, finalization, and task disposition. For chat/email work, follow outbound delivery and the user-visible result too. Align run events, logs, controller/provider records, task activity, and traces by time and identity.
Separate these questions:
Answer early whether the failing step resumed state saved by a different release. If it did, compare what the old release persisted with what the new one requires before pursuing provider, model, or capacity explanations.
Trace the causal value or transition to its producer and shared contract. Verify the hypothesis against a counterexample or a reproduction. Check logs before and after the apparent error: a recovered authorization warning may not be fatal, and “final response,” HTTP 200, or “run succeeded” may not mean the task is complete. Missing error detail is an evidence gap, not proof of a provider outage. When evidence cannot distinguish hypotheses, name the uncertainty and add the smallest bounded, redacted observation or fault injection that will resolve it.
For a stalled tree, classify each relevant non-progressing node as genuinely waiting on a named human/external dependency, agent-actionable but unrouted, or already covered by existing work. Preserve all three invariants:
Consult failure patterns for matching mechanisms and test oracles. Treat them as hypotheses to check, not a catalog of explanations.
Write the smallest behavioral regression at the boundary that owns the defect. Run it against the unfixed code and capture the expected failure. A setup error, missing dependency, or assertion about a mock's own return value is not the red.
Keep this failing regression as the starting point for the repair. If the defect requires a real integration environment, capture a repeatable failing integration probe before the fix and repeat it afterward; add a durable regression at the closest reliable boundary. If no meaningful red can be observed, report that gap and keep working on reproduction. Do not claim red-green proof from a test that was first run after the fix.
Before changing a failing guard, name the invariant it protects. If existing runtime checks already establish compatibility, remove redundant prerequisites instead of adding qualification machinery; retain authority and integrity checks.
Fix the responsible producer or shared transition at the narrowest correct scope. Check sibling callers/adapters that share that contract; generalize only as far as 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 runtime variants affected by the changed contract. Turn the important safety assumptions into observable regression cases, not just assurances in the PR:
Select cases that exercise the actual blast radius. Do not create an unrelated platform matrix. Test the sibling success path and the negative case that the old guard protected. Keep reproduction and safety tests through later revisions.
Upgrade safety is part of every repair that touches persisted run identity:
launch arguments, provider/runner pack digests, leases, listeners, session or
checkpoint schema, and workspace authority. Each must either carry forward across
releases or fail with a permanent, named code, never a generic retryable one such
as native_session_interrupted. A retry cannot change saved identity; it repeats
the refusal or replaces saved state. Add an old-saved/new-resumed regression using
state shaped by the previous release, and a deploy-lands-mid-run case when the run
can be in flight at the cutover. Prefer one class-level rule at the shared
admission or recovery boundary over another per-error-code exception. For remote
sandbox paths, test with the provider's confinement rules applied; a local test
without them does not prove the remote path.
With the red established and the safety assumptions identified, make the repair and run the same regression green. Run the relevant safety cases and existing tests. Refactor only while they stay green. Investigate unexpected failures instead of weakening an assertion or deleting the regression to finish.
Routine infrastructure facts belong to the harness when it can determine them under existing authority. Reconcile process ownership, saved results, or eligible continuations in code instead of asking a user to certify those facts in a form. Keep UI choices for genuine user intent, authorization, or unavailable information.
Apply the repository's verify-paperclip skill and affected map recipes when
available. Its essential requirement here is a real run through the affected user
entry point, using the fixed source or package and the relevant runtime configuration.
Run the narrow regression first so each hypothesis gets fast feedback; use a local
server with the real remote provider when that reproduces the failure. Do not wait
for a full deployment for every experiment when a faithful shorter loop exists.
Exercise the original failure mechanism with a representative task: actual adapter, provider, tools, trust boundary, persisted state, artifact, and interruption point where each matters. A mock, Storybook, provider-free benchmark, or generic “hello” smoke is supporting evidence only when the incident depends on a different path.
Verify the useful output, persistence after reload/reconnect, finalization, and correct task state with no stranded lock or pending operation. For resume and conversation defects, run a second turn and check retained context/files. For delivery defects, check the destination and user-visible outcome, not just receipt of an HTTP request. For slowness, compare the end-to-end interval with the baseline.
Record the tested revision and runtime versions. Re-run affected acceptance after changes that invalidate that evidence. Report any missing credentials, access, or environment precisely; an unavailable live check remains unverified. Continue independent repair and PR work instead of substituting an unsupported “works” claim.
Use prepare-paperclip-pr and prcheckloop when available. Follow repository
instructions for checks, branch isolation, PR template, and review. Open the PR,
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. Do not declare it ready while required checks or review remain unresolved. If a required service or permission prevents completion, name the exact remaining gate.
When rollout/recovery is already authorized, continue: confirm the served revision and required artifact versions, re-read the original task, and recover it through the normal product path. Reconcile existing work before starting another executor. Observe the original useful result or a genuine, named remaining blocker. Do not cancel, replace, or shrink the user's original task merely to make a test pass.
Finish with a concise report:
Do not stop at a plan when a fix is authorized. Do not call the incident resolved because its error message improved or a successful run badge appeared.
Diagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check secon
---name: fix-failed-paperclip-rundescription: Diagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL…---# .agents/skills/fix-failed-paperclip-run/SKILL.mdОбзор
Diagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.
FAQ
Скачайте .agents/skills/fix-failed-paperclip-run/SKILL.md у издателя или скопируйте путь и откройте репозиторий. PlugMCP только показывает навык в каталоге и не хранит файл.
Издатель хранит его в https://github.com/paperclipai/paperclip.
Claude, Cursor, Codex и Grok Build могут читать SKILL.md, который вы добавляете из репозитория издателя. Grok Bot устанавливает его, когда вы отправляете в чат ссылку на папку навыка на GitHub.