# Fix Failed Runs

Traces the root cause of a failed or stuck task and delivers a verified fix.

- Repository: https://github.com/paperclipai/paperclip (109885 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add paperclipai/paperclip --skill fix-failed-paperclip-run -g -a claude-code -y`
Codex: `npx skills add paperclipai/paperclip --skill fix-failed-paperclip-run -g -a codex -y`
Cursor: `npx skills add paperclipai/paperclip --skill fix-failed-paperclip-run -g -a cursor -y`
Gemini CLI: `npx skills add paperclipai/paperclip --skill fix-failed-paperclip-run -g -a gemini-cli -y`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.

## 1. Establish the incident and the finish line

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:

- Instance, company, task, affected run(s), time window, and intended useful result.
- Current state versus state at failure; parent/child tasks and pending interactions
  only where they control progress. Multiple failed runs can have different causes.
- The code actually served, runner/provider pack versions, operating system and
  architecture, adapter, model/effort, execution workspace, trust mode, and credential
  source. Trace effective values back through task overrides, inherited settings,
  defaults, and saved session state. Redact credential values.
- Which endpoint is authorized: verified fix and green PR, or also rollout and
  recovery. Preserve the requested work and success criteria throughout.

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.

The rest: https://github.com/paperclipai/paperclip/blob/HEAD/.agents/skills/fix-failed-paperclip-run/SKILL.md