| 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:
npm ci && npm test
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
