ship-error-handling — Claude Code command: /ship recovery
The ship-error-handling command documents how to recover /ship from CI failures, merge conflicts, deployment errors, and other shipping problems.
MIT ★ 2,003 updated 2026-07-26
/plugin marketplace add composio-community/awesome-claude-plugins
/plugin install ship@awesome-claude-pluginsWhat ship-error-handling does
The command’s reference explains what to do when gh is missing, CI fails, a push is rejected, or PR creation does not work. For CI problems, it outlines how to retry /ship after pushing a fix and how to delegate the failure to next-task:ci-fixer.
For merge conflicts, it walks through fetching and merging the main branch before trying again. Deployment sections point to logs from railway, vercel, or netlify, while a failed production validation triggers a rollback procedure. Force pushes use --force-with-lease to avoid overwriting unexpected remote changes.
It also covers unresolved review threads and worktree cleanup. Set SHIP_DEBUG=1 to get detailed phase output. GitHub procedures depend on the GitHub CLI being installed and authenticated with gh auth login; without that, those steps cannot run.
What it helps with
- resume shipping after fixing a CI failure
- resolve a merge conflict before retrying
/ship - inspect deployment logs after a failed release
- roll back production after validation fails
- clean up a worktree that could not be removed
Example prompts for the agent
- Explain how to fix this PR's CI failure and resume with
/ship. - Walk me through resolving the conflict with the main branch, then restarting
/ship. - Show the recovery steps for a deployment failure and enable
/shipdebug logging.
How to install ship-error-handling
1Plugin marketplace
/plugin marketplace add composio-community/awesome-claude-plugins/plugin install ship@awesome-claude-plugins2Manually: put the files in place
.claude/commands/ship-error-handling.mdCall it with /ship-error-handling. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/ship-error-handling.mdCall it with /prompts:ship-error-handling. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/ship-error-handling.prompt.mdManually: put the files in place
.gemini/commands/ship-error-handling.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about ship-error-handling
How do I install ship-error-handling in Claude Code?
Run /plugin marketplace add composio-community/awesome-claude-plugins, then /plugin install ship@awesome-claude-plugins. The command file is at .claude/commands/ship-error-handling.md.
What does ship-error-handling do?
It provides recovery steps for /ship when CI, GitHub operations, merges, deployments, or production validation fail. It includes commands for troubleshooting and resuming the workflow.
Does ship-error-handling require GitHub CLI?
GitHub procedures require gh and authentication through gh auth login. For CI failures, the reference also describes handing the issue to next-task:ci-fixer.
Source text
ship-error-handling.md · MIT
# Error Handling & Recovery - Reference
This file contains error handling procedures for `/ship`.
**Parent document**: `ship.md`
## GitHub CLI Not Available
```markdown
ERROR: GitHub CLI (gh) not found
Install: https://cli.github.com
Or use package manager:
macOS: brew install gh
Windows: winget install GitHub.cli
Linux: See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
Then authenticate:
gh auth login
```
## CI Failure
```markdown
[ERROR] CI checks failed for PR #${PR_NUMBER}
View details:
${CI_URL}
Fix the failing tests/checks and push again.
The /ship command will resume from Phase 4 (CI monitoring).
To retry:
git push
/ship
```
### CI Fix with ci-fixer Agent
When CI fails, use the ci-fixer agent:
```javascript
Task({
subagent_type: "next-task:ci-fixer",
prompt: `Fix CI failure for PR #${PR_NUMBER}
CI Output:
${CI_OUTPUT}
Failed checks:
${FAILED_CHECKS}
Requirements:
1. Analyze the failure reason
2. Make minimal fix to pass CI
3. Do not introduce unrelated changes
4. Ensure all tests pass after fix`
});
```
## Merge Conflicts
```markdown
[ERROR] Cannot merge PR #${PR_NUMBER}: conflicts with ${MAIN_BRANCH}
Resolve conflicts:
git fetch origin
git merge origin/${MAIN_BRANCH}
# Resolve conflicts in your editor
git add .
git commit
git push
Then retry:
/ship
```
## Deployment Failure
```markdown
[ERROR] Deployment failed
${WORKFLOW === 'dev-prod' ? 'Development' : 'Production'} deployment did not succeed.
Check deployment logs:
${DEPLOYMENT === 'railway' ? 'railway logs' : ''}
${DEPLOYMENT === 'vercel' ? 'vercel logs' : ''}
${DEPLOYMENT === 'netlify' ? 'netlify logs' : ''}
Once fixed, deployment will retry automatically.
```
## Production Validation Failure with Rollback
```markdown
[ERROR] Production validation failed
ROLLBACK INITIATED
Production has been rolled back to previous version.
Previous deployment: ${PREVIOUS_SHA}
Issues detected:
${VALIDATION_ISSUES}
Fix the issues and try shipping again:
/ship
```
## Push Failure
```markdown
[ERROR] Push to remote failed
Possible causes:
1. Authentication issue: gh auth status
2. Remote branch protected: check branch protection rules
3. Out of date: git pull --rebase origin ${CURRENT_BRANCH}
Resolve and retry:
/ship
```
## PR Creation Failure
```markdown
[ERROR] Failed to create PR
Possible causes:
1. Already exists: gh pr list --head ${CURRENT_BRANCH}
2. No commits: git log ${MAIN_BRANCH}..HEAD
3. Same branch: ensure not on ${MAIN_BRANCH}
Check existing PRs:
gh pr list --state all --head ${CURRENT_BRANCH}
```
## Max Review Iterations Reached
```markdown
[ERROR] Max iterations (${MAX_ITERATIONS}) reached
Unable to resolve all review comments automatically.
Manual intervention required.
Remaining unresolved threads: ${UNRESOLVED_COUNT}
View PR: ${PR_URL}
Options:
1. Manually address remaining comments
2. Request reviewer to close non-blocking items
3. Continue with /ship after resolving
```
## Worktree Cleanup Failure
```markdown
[WARN] Failed to clean up worktree
Worktree at: ${WORKTREE_PATH}
Manual cleanup:
git worktree remove ${WORKTREE_PATH} --force
git worktree prune
```
## Force Push Safety
When rollback requires force push:
```bash
# ALWAYS use --force-with-lease instead of --force
# This prevents overwriting unexpected remote changes
if ! git push --force-with-lease origin $PROD_BRANCH; then
echo "[ERROR] Force push failed - remote has unexpected changes"
echo "Someone else may have pushed to production"
echo "Manual investigation required"
exit 1
fi
```
## Recovery Procedures
### Resume After CI Fix
```bash
# After fixing CI locally
git add .
git commit -m "fix: address CI failures"
git push
# Resume shipping
/ship
```
### Resume After Conflict Resolution
```bash
# After resolving merge conflicts
git add .
git commit
git push
# Resume shipping
/ship
```
### Resume After Manual Review Resolution
```bash
# After manually addressing review comments
git add .
git commit -m "fix: address review feedback"
git push
# Resume shipping
/ship
```
### Cancel and Cleanup
```bash
# If you need to abandon the PR
gh pr close $PR_NUMBER --delete-branch
# Clean up local
git checkout $MAIN_BRANCH
git branch -D $CURRENT_BRANCH
```
## Exit Codes
| Code | Meaning |
|------|---------|
| 0 | Success - PR merged |
| 1 | General failure |
| 2 | CI failure (retryable) |
| 3 | Review timeout (manual intervention) |
| 4 | Deployment failure |
| 5 | Rollback triggered |
## Logging for Debugging
Enable verbose logging:
```bash
export SHIP_DEBUG=1
/ship
```
This will output detailed information about each phase for troubleshooting.
© Community · MIT · composio-community/awesome-claude-plugins