fix-failing-tests

Diagnose and Fix Failing Tests

Scope: googleapis/mcp-toolbox

Debug the way a careful developer does. Read the real error, find out what changed, reproduce it, shrink it until the cause is forced into the open, then fix the cause rather than the symptom.

The Evidence Rule

Every factual claim MUST cite evidence: a path with line numbers, a build ID, a log excerpt, or a SHA. Otherwise mark it [UNVERIFIED] and say what would confirm it.

Open every line you cite, including this skill's. Ensure all pointers are correct.

1. Read the actual failure

How you arrived decides what evidence you already hold and how much of step 2 you can skip.

You arrived from	What you have	Where that puts you
A gate failing on your PR	A diff and a known-good parent	Your change is the prime suspect, but confirm the same job is green on main before assuming it
A periodic-failure issue	A build link buried in a long thread	Take the newest comment's link. The title often describes a different, already-fixed failure
An issue someone filed	A claim, often without a log	Establish that it still fails before anything else. Reports go stale, and the fix may have landed already
main is red	A range of commits, none of them yours	Bisect over merges. Say you are inheriting it rather than absorbing it into your change
Fails locally, green in CI	A reproduction	Suspect your environment: stale build cache, leftover local state, missing env, different Go version
Green locally, fails in CI	Neither	Suspect what CI does differently: -race, another OS, concurrency, a clean checkout, no cached state

Whatever the door, get to the real error before theorising. Do not work from the job summary or the last line of the log. Find the first real error and read it in full.

• Did a test fail at all? Some red jobs contain zero failing tests: a compile error before the test step, a coverage threshold, a separate lint job, or a shard that skipped itself. Confirm a real test failure before debugging one. references/ci-map.md lists the jobs that go red with everything green.
• Which error is the cause? Compile errors cascade, so the first is the cause and the rest are consequences. Assertion failures do not cascade, so read them all: three unrelated ones mean something different from thirty identical ones.
• What kind of failure is it? An assertion, a panic, a timeout, and a connection error each imply a different investigation. A connection error in a test that never touches the network usually means the process under test died.
• What exactly was expected versus produced? Get the diff, the test name, and the subtest name. "The test failed" is not a starting point.