ci-debug-workflow

name	ci-debug-workflow
description	Debug failing CI pipelines, containers, and reproduce bugs locally. Use when CI is red, containers won't start, or need to reproduce bugs.

CI Debug Workflow

Debug failing CI pipelines, containers, and reproduce bugs locally.

Trigger Patterns

• "fix failing CI"
• "debug this pipeline"
• "why is CI red"
• "container won't start"
• "reproduce this bug"

Workflow

1. Gather Context

Read CI logs first. Identify:

• Which step failed
• Error message/stack trace
• Environment differences from local

For bug reports, extract reproduction steps. See bug-thread-extraction.md.

2. Reproduce Locally

Never fix blind. Reproduce failure before changing code:

# Run same commands CI runs
npm ci && npm test

# Or match CI environment
docker build -t debug-image .
docker run --rm debug-image npm test

3. Identify Root Cause

Common CI failure patterns in ci-patterns.md:

• Dependency version mismatches
• Missing environment variables
• Timing/race conditions
• Platform differences (Linux vs macOS)

Container issues in docker-debug.md.

4. Apply Fix

Fix the actual issue, not symptoms:

• Pin dependency versions explicitly
• Add missing env vars to CI config
• Fix flaky tests with proper waits
• Use platform-agnostic paths

5. Verify

Push fix and confirm CI passes. Do not mark done until green.

git push && gh run watch

Anti-patterns

• Rerunning CI hoping it passes
• Fixing locally without reproducing CI environment
• Disabling failing tests
• Adding broad || true to mask failures

References

• ci-patterns.md - Common CI failure patterns
• docker-debug.md - Container troubleshooting
• bug-thread-extraction.md - Parse bug reports