when ci fails, investigate first

why red pull request checks are a signal to isolate root cause rather than trigger a broad code rewrite, and how a targeted investigation loop keeps agent changes safe.

quick answer

when a pull request check goes red, the most expensive mistake is asking an agent to start editing files right away. generation is fast, but unguided fixes often edit unrelated code, hide cascading failures, or break surrounding contracts. treat the agent as a diagnostic tool first. isolate the exact failing job, map the error log to changed paths, and only then apply a fix.

who this is for

• audience: developers, analytics engineers, and technical leads using ai coding agents in pull-request workflows
• prerequisites: familiarity with continuous integration (ci) checks, pull request reviews, and command-line execution
• when to use this guide: when a pull request check fails and you need to resolve the failure without generating unnecessary code churn

context

when a continuous integration run turns red on a pull request, the natural impulse with an ai assistant in your editor is to ask it to fix the build immediately. it takes two seconds to paste a snippet of a failing log and ask the agent to make it green.

but when you tell an agent to fix a build without isolating the failure first, the agent treats the red check as a license to touch anything in sight. it refactors adjacent models, tweaks test configurations, or rewrites helper functions that were not part of the problem.

as i wrote in reading the diff is the whole job, human review capacity is the sole bottleneck in ai-assisted engineering. unguided fixes flood your pull request diff with low-intent changes, making review harder and hiding the original bug behind new ones.

the rewrite trap

when an agent attempts to fix a ci failure blindly, the failure usually compounds in one of three ways:

• the shotgun edit: the agent edits business logic, documentation yaml, and CI configuration files in a single pass because the log tail contained a generic error message.
• the wrong layer: a failure in a downstream view causes the agent to rewrite upstream models or warehouse schemas that were completely sound.
• the environment disconnect: the agent modifies code locally to pass a test without recognizing that ci failed due to state selection, missing secrets, or workflow ordering.

the investigation loop

instead of letting an agent edit code on the first prompt, use a structured loop that treats the agent as a diagnostic tool before giving it write access.

1) freeze writes and isolate the failure

stop all code changes. do not allow the agent to edit files until you identify the single highest-order failed check. if a deploy step failed, downstream test failures are secondary noise and should be ignored until the deploy issue is understood.

2) classify the error type

ask the agent to categorize the exact nature of the failure from the log output into one of four buckets:

• parse or compile error: syntax bugs, missing references, or macro failures
• data quality or test failure: assertion failures or row-count mismatches
• environment or configuration failure: missing environment variables, permissions, or secret mismatches
• workflow or state failure: invalid state selection flags or missing upstream artifacts in slim ci

3) map log lines to changed paths

match the error message directly back to the files changed in your pull request diff. if the error occurs in a file you did not touch, ascertain whether your change caused a breaking side effect or if the test failed due to an external dependency or stale target state.

4) apply one fix and re-run

once the root cause is isolated, prompt the agent to apply a minimal fix targeting only that specific cause. change only one variable at a time so you know exactly which modification resolved the issue. review the resulting diff carefully before committing and pushing the change.

related reading

• reading the diff is the whole job
• cursor automations for housekeeping and hygiene
• the guardrails i actually use with ai agents
• practical ai workflow in cursor: connecting jira, github, and mcp