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