# Error Recovery

> Error Recovery Playbook

- Skill: `nickgallick/error-recovery` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nickgallick/error-recovery`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nickgallick/error-recovery/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nickgallick (https://skillmd.com/u/nickgallick)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/nickgallick/error-recovery

---

# Error Recovery Playbook

Standardized procedures for every known failure mode. When something goes wrong, find the matching scenario and follow the playbook. Do not improvise unless no playbook exists — and if that happens, document the new scenario afterward.

---

## Agent Unresponsive

**Symptoms:** Agent does not respond within expected time window. No output, no error, no acknowledgment.

**Playbook:**

1. **Retry (immediate):** Resend the same `sessions_send` message. Agents may have missed the initial message due to transient issues.
2. **Wait 3 minutes.** Some tasks take longer than expected. Give the agent a reasonable buffer.
3. **First nudge:** Send a status check message: "Status update requested — are you still working on {task}?"
4. **Wait another expected-duration window.**
5. **Second nudge:** Send with urgency: "Second status check — {task} is blocking the pipeline. Please respond with current status or any blockers."
6. **Check with ClawExpert:** Send ClawExpert a diagnostic request: "Is {agent name} reachable? Any infrastructure issues affecting agent availability?" ClawExpert may identify system-level problems.
7. **Escalate to Nick:** If still no response after 2 nudges and ClawExpert check, report to Nick:
   - Which agent is unresponsive.
   - What task they were assigned.
   - How long they've been unresponsive.
   - What you've tried.
   - Recommended action (wait longer, reassign task, manual intervention).

---

## V0 API Failure

**Symptoms:** Pixel reports V0 API is down, timing out, or returning errors. Design pipeline cannot proceed.

**Playbook:**

1. **Retry (immediate):** Ask Pixel to retry the V0 request. Transient failures are common.
2. **Wait 2 minutes and retry again.** V0 outages are often brief.
3. **Stitch fallback:** If V0 remains unavailable, instruct Pixel to switch to Stitch for design generation. Note in the project file that Stitch was used (reduced fidelity).
4. **Text-based specs fallback:** If both V0 and Stitch are unavailable, instruct Pixel to produce detailed text-based design specifications:
   - Layout descriptions with exact measurements.
   - Color values and typography specs.
   - Component hierarchy and behavior descriptions.
   - Wireframe-level sketches if possible.
5. **Note the fallback** in the project file and in the handoff to Maks so he knows designs are text-based and should use best judgment for visual details.
6. **Report to Nick** if the fallback significantly impacts quality or timeline.

---

## Forge Blocks 3+ Times (Circuit Breaker)

**Symptoms:** Maks and Forge have completed 3 fix loops and Forge still has not approved. The circuit breaker has triggered.

**Playbook:**

1. **Stop the loop immediately.** Do not send a 4th fix request to Maks.
2. **Compile a summary:**
   - Original issues Forge raised in loop 1.
   - What Maks fixed in each loop.
   - Remaining issues Forge is still flagging.
   - Pattern analysis: Are these the same issues recurring, or new issues each time?
3. **Escalate to Nick with 3 options:**

   > **Option A: Ship with known issues.**
   > The remaining issues are [{list}]. None are P0 security/data-loss risks. We document them as known issues and address in a follow-up iteration.

   > **Option B: Bring in additional context.**
   > Forge and Maks may be misaligned on [{specific area}]. Nick can provide clarification or additional requirements that resolve the disagreement.

   > **Option C: Redesign the problematic section.**
   > The issues stem from [{root cause — e.g., a specific component, architectural decision}]. Send the affected screen(s) back to Pixel for redesign, then rebuild.

4. **Wait for Nick's decision.** Do not proceed until Nick picks an option or provides an alternative direction.

---

## Build Fails to Deploy

**Symptoms:** Maks reports a deployment failure. Preview or production URL is not accessible.

**Playbook:**

1. **Get the error.** Ask Maks for the exact error message, stack trace, or deployment log output.
2. **Categorize the error:**
   - **Code error** (build fails, type errors, missing imports): Maks debugs and retries. This is within Maks's domain.
   - **Infrastructure error** (DNS, SSL, Vercel config, environment variables, permissions): Consult ClawExpert.
   - **Dependency error** (package conflicts, version mismatches): Maks resolves, or consult ClawExpert if it's a system-level issue.
3. **If code error:** Tell Maks the specific error and ask for a fix. Allow 2 attempts.
4. **If infrastructure error:** Send ClawExpert the error with context:
   - What was being deployed.
   - The deployment platform and configuration.
   - The exact error message.
   - Wait for ClawExpert's diagnostic and fix.
5. **If still failing after 2 Maks attempts + ClawExpert consultation:** Escalate to Nick with the error details and what's been tried.

---

## Design Mismatch After Build

**Symptoms:** QA or visual inspection reveals that the build doesn't match Pixel's designs for specific screens.

**Playbook:**

1. **Identify the specific mismatches.** Document which screens don't match and what's different (layout, colors, spacing, missing elements, wrong behavior).
2. **Assess severity:**
   - **Minor** (slight spacing, color shade): Note for Maks with specific corrections. No need to involve Pixel.
   - **Major** (wrong layout, missing sections, broken user flow): Send back to Maks with Pixel's original specs highlighted.
3. **Send Maks targeted fix requests** for each mismatched screen:
   - Reference the specific Pixel design (V0 chat ID, preview URL).
   - Point out exactly what's different.
   - Ask for a match to the design, not a "close enough."
4. **If Maks cannot match the design** due to technical constraints, notify Pixel and ask for an alternative design approach that's feasible to implement.
5. **Re-QA the fixed screens** before proceeding.

---

## Nick Changes Requirements Mid-Build

**Symptoms:** Nick sends updated requirements while the project is in BUILD, REVIEW, or later phases.

**Playbook:**

1. **Acknowledge immediately.** Tell Nick you've received the changes and are assessing impact.
2. **Assess the change type:**
   - **Cosmetic** (copy changes, color tweaks, minor layout adjustments): Send directly to Maks as a patch. No need to loop back to earlier phases.
   - **Structural** (new screens, removed screens, different user flows, new features, changed backend requirements): Requires re-evaluation.
3. **For cosmetic changes:**
   - Send Maks the specific changes.
   - Note the change in the project file.
   - Continue the pipeline from current phase.
4. **For structural changes:**
   - Pause the current pipeline.
   - Update the project file with the new requirements.
   - Determine which phase to re-enter:
     - New screens → Back to DESIGN for those screens only.
     - New features/backend → Back to DESIGN or BUILD depending on scope.
     - Changed ICP/positioning → Back to RESEARCH.
   - Report to Nick: "Structural change received. This resets us to {phase}. New ETA: {estimate}."
5. **Never silently absorb structural changes.** Always report the impact to Nick.

---

## Gateway Crash / MaksPM Restart

**Symptoms:** MaksPM loses context — conversation resets, memory is gone, no awareness of active projects.

**Playbook:**

1. **Read active-projects/.** List all project files and their current states.
2. **For each active project:**
   - Read the project file to determine current phase and last activity.
   - Check the Phase Log for the most recent transition.
   - Identify what was in progress when the crash occurred.
3. **Resume from the project file.** The project file is the source of truth. Pick up from the last completed phase:
   - If a brief was sent but no response received → Resend the brief.
   - If a response was received but the gate wasn't checked → Run the gate check.
   - If a phase was complete but the next wasn't started → Start the next phase.
4. **Send Nick a recovery report:**
   - "MaksPM restarted. Recovered {n} active project(s). Current status: {summary per project}. Resuming from last known state."
5. **Re-establish contact with any agents that had pending tasks** via `sessions_send` status checks.

---

## Subagent Spawn Failed or Timed Out
1. Check if the spawn completed: look at the auto-announce message for errors
2. If timeout (no response after runTimeoutSeconds): spawn again with longer timeout
3. If agent errored: read the error, fix the task prompt, spawn again
4. After 2 failed spawns → escalate to Nick: "[Agent] failed twice on [task]. Error: [details]. Options: (A) retry with different approach (B) skip this phase (C) you intervene"

## Subagent Returns Incomplete Work
1. Check what's missing against the quality gate
2. Spawn the same agent again with: "Previous output was incomplete. Missing: [specific items]. Complete only the missing items."
3. If still incomplete after retry → proceed with what you have + note the gap to Nick

## Auto-Announce Didn't Arrive
1. Check sessions_list for the spawned session — is it still running?
2. If still running → wait (don't re-spawn and create duplicates)
3. If completed but no announce → read result via sessions_history with the session key
4. If session doesn't exist → spawn again