Debug pipeline

Skill LuisHiluy/claude-code-pipeline-skills/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.From its SKILL.md

Install

npx -y skills add LuisHiluy/claude-code-pipeline-skills --skill debug-pipeline

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.7 KB, 488 tokens by cl100k_base, as published. Nobody here has run it

Debug Pipeline — AI Media Runbook

Structured diagnostic for when the generation pipeline breaks.

Quick Diagnostic

Run the full check first:

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

Or target a specific component:

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

What ships with it: 3 files

4.4 KB alongside SKILL.md, 1 of them executable

reference/

symptom-map.md2.4 KB

scripts/

check-pipeline.shruns1.4 KB

README.md653 B

Gives 0 of the 12 instructions most debug triage skills give in 488 tokens

Counted across 839 of the 1,149 authors here whose files we hold, read 2026-08-07

Investigate root cause before proposing any fixin 102 of 839, across 67 files
Read error messages completelyin 89 of 839, across 49 files
Create a failing test case before fixingin 84 of 839, across 46 files
Reproduce the issue consistentlyin 82 of 839, across 41 files
Change one variable at a timein 82 of 839, across 42 files
Check recent changesin 74 of 839, across 36 files
Write the regression test before fixingin 74 of 839, across 40 files
Fix the root cause not the symptomin 60 of 839, across 45 files
Implement a single fix at a timein 59 of 839, across 20 files
Trace data flow backward to the sourcein 50 of 839, across 20 files
Remove all debug instrumentationin 49 of 839, across 13 files
Form a single hypothesisin 48 of 839, across 18 files

Said here and by no other author read

look up symptoms in the symptom map
re-authenticate the generator for stuck generation
remove stale worker lock files before restarting
restart servers from launch config when down
check prompt uses descriptors instead of names
reduce parallel batch size when rate limited

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.