CI Failure Triage

CI Failure Triage

Use this skill to isolate failing CI causes with deterministic artifact checks.

Gait Context

Gait is the offline-first policy-as-code runtime for AI agent tool calls. It enforces tool-boundary policy, emits signed and verifiable evidence artifacts, and supports deterministic regressions.

Use this skill when:

• incident triage requires artifact-first root-cause isolation
• CI gate failures need deterministic reruns tied to a failing artifact
• evidence outputs must be generated from Gait artifacts

Do not use this skill when:

• Gait CLI is unavailable in the environment
• no Gait run/pack artifact or run identifier is available as input

Required Inputs

• failure_target: failing run id, runpack path, or pack path.
• baseline_target (optional): known-good runpack or pack for diff.
• workdir: writable directory for triage outputs.

Workflow

1. Verify the failing artifact first:
   • gait verify <failure_target> --json
2. Resolve path-based targets before changing directories:
   • keep identifiers unchanged (for example run ids)
   • if <failure_target> is a relative file path, normalize to absolute path
   • if <baseline_target> is provided as a relative file path, normalize to absolute path
   • failure_target_ref="$(python3 -c 'import os,sys; v=sys.argv[1]; print(os.path.abspath(v) if os.path.exists(v) else v)' <failure_target>)"
   • baseline_target_ref="$(python3 -c 'import os,sys; v=sys.argv[1]; print(os.path.abspath(v) if os.path.exists(v) else v)' <baseline_target>)" (only when provided)
3. Enter an isolated triage workspace:
   • mkdir -p <workdir> && cd <workdir>
4. If failure came from regress grading, bind reruns to the requested target:
   • explicit path: gait capture --from <failure_target_ref> --json
   • then gait regress add --from ./gait-out/capture.json --json
   • gait regress run --json
5. If baseline evidence exists, compute deterministic diff:
   • gait pack diff <baseline_target_ref> <failure_target_ref> --json
6. If environment health is uncertain, run diagnostics:
   • gait doctor --json
7. Return triage summary:
   • integrity status
   • failing stage and reason codes
   • diff highlights (if provided)
   • exact next command to reproduce

Safety And Portability Rules

• Never classify root cause without command output evidence.
• Do not rely on CI provider-specific APIs when local artifacts are available.
• Preserve stable exit-code semantics in reporting.
• Keep recommendations reproducible with copy-pastable commands.

Usage Example

gait demo --json
gait verify run_demo --json
failure_target_ref="$(python3 -c 'import os,sys; v=sys.argv[1]; print(os.path.abspath(v) if os.path.exists(v) else v)' run_demo)"
mkdir -p ./triage && cd ./triage
gait capture --from "${failure_target_ref}" --json
gait regress add --from ./gait-out/capture.json --json
gait regress run --json
gait doctor --json

Expected result:

• verify output reports integrity status for the target artifact
• fixture creation output references the requested failure_target
• doctor output reports actionable diagnostics
• regress output reports stable pass/fail status and failures

Validation Example

gait demo --json
mkdir -p ./artifacts
gait verify run_demo --json > ./artifacts/verify.json
python3 - <<'PY'
import json
from pathlib import Path
p = json.loads(Path('./artifacts/verify.json').read_text(encoding='utf-8'))
assert 'ok' in p
assert 'run_id' in p or 'bundle' in p
print('validated verify payload keys present')
PY

Expected result:

• script prints validated verify payload keys present