# Debug Pipeline

> Structured diagnostic runbook for broken AI media pipelines. Walks through symptom → root cause → fix for generator auth failures, stale worker locks, review-app crashes, MCP auth errors, rate limits, and corrupted state files. Use whenever generation jobs fail, workers stop picking up tasks, generated output looks wrong, review tools break, MCP servers error, or any multi-component failure happens in an AI media pipeline. Trigger on "debug the pipeline", "generation is broken", "worker not running", "review app down", "why is this failing", "what's wrong with the pipeline", or anytime the user reports a symptom without yet knowing the root cause.

- Skill: `luishiluy/debug-pipeline` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add luishiluy/debug-pipeline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luishiluy/debug-pipeline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: LuisHiluy (https://skillmd.com/u/luishiluy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/luishiluy/debug-pipeline

---


# Debug Pipeline — AI Media Runbook

Structured diagnostic for when the generation pipeline breaks.

## Quick Diagnostic

Run the full check first:

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" all
```

Or target a specific component:

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" generator
bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" worker
bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" review-app
bash "${CLAUDE_SKILL_DIR}/scripts/check-pipeline.sh" mcp
```

Customize the script for your pipeline's components.

## Diagnostic Flow

```
Symptom reported
  ↓
Run check-pipeline.sh all → identify which component is failing
  ↓
Look up symptom in reference/symptom-map.md → follow specific steps
  ↓
Output structured finding:
  - Component: [generator | worker | review-app | mcp | database]
  - Symptom: [what was observed]
  - Root cause: [what the check found]
  - Fix: [specific command or action]
  - Verified: [did the fix work — re-run check-pipeline.sh]
```

## Common Fixes (80% of issues)

| Symptom | Fix |
|---|---|
| Generation stuck | Re-auth the generator |
| Worker not running | Remove stale lock: `rm runs/worker.lock`, restart |
| Review app down | Restart servers from launch config |
| Wrong character | Check prompt uses descriptors not names, add reference images |
| API rate limit | Back off, reduce parallel batch size |

## Detailed Symptom Map

For full symptom → diagnostic → fix chains, see [reference/symptom-map.md](reference/symptom-map.md). Extend this file as you discover new failure modes.

## Gotchas

- Web-auth tokens expire. If anything generation-related fails, check auth first.
- Worker lock files persist if the worker crashes. Always check if the PID is actually alive before assuming the worker is running.
- Port proxies — if your backend is on port X and your proxy is on port Y, check both. A silent failure on X looks like a failure on Y.
- Review data files are often the source of truth for metadata. If they get corrupted, restore from git.