CI Health Gate Runbook

This runbook covers triage for Sprint readiness CI failures in:

• .github/workflows/ci-pr.yml
• .github/workflows/slack-notify.yml
• scripts/ci/run_health_gate.sh

What the gate currently checks

1. scripts/ci/run_smoke.sh - backend_v2 integration smoke tests - frontend integration smoke test
2. backend_v2/tests/integration/cli_hooks_smoke.py - placeholder synthetic checks for upcoming CLI doctor and data commands
3. scripts/ci/validate_chart_exports.py (non-blocking in current wave) - CSV: header/schema + row quality + fixture content diff checks - PDF: header/EOF/page-marker integrity checks when artifact exists - JPEG: SOI/EOI/dimension integrity checks when artifact exists

Fast triage flow

1. Open the failed GitHub Actions run URL from the PR comment.
2. Identify which step failed: - Run health gate checks - Slack Notify
3. Reproduce locally from repo root: - bash scripts/ci/run_health_gate.sh
4. Fix and rerun only the failing scope first, then rerun the full gate.

Common failure patterns

• Python dependency/test bootstrap failures
• Symptom: pytest import/module errors in backend_v2 tests

• Action: verify Python deps in scripts/ci/run_smoke.sh are still sufficient

• Frontend smoke failures

• Symptom: integration smoke test exits non-zero

• Action: run npm --prefix frontend/trademaster_ui run test:integration-smoke locally

• Chart export QA warning/failure signals

• Symptom: chart export report contains warn/fail findings
• Action: inspect artifacts/chart-export-validation.json:
  • summary.semver_signal
  • summary.actionable_failures[]
  • summary.actionable_warnings[]

• Use check_code, message, and remediation to triage quickly.

• Slack message not sent

• Symptom: Slack workflow succeeds but no channel message
• Action: check SLACK_WEBHOOK_URL secret exists; if not, this is expected safe behavior

Secret-safe behavior

• slack-notify.yml never prints webhook values.
• If SLACK_WEBHOOK_URL is absent, workflow records a summary message and exits without failure.
• CI gate does not require external Alpaca secrets yet; external synthetics remain an incremental follow-up.
• Chart export QA remains non-blocking by default unless script is run with --strict.

Incremental hardening backlog (next step to production-grade)

1. Replace placeholder CLI hooks with real doctor command checks.
2. Add explicit synthetic probes for critical data/trading contracts with retry policy.
3. Add actionlint or equivalent workflow lint enforcement in CI.
4. Add alert routing/escalation policy for repeated gate failures.