# Fix a flaky test, or quarantine it with the cause written down

One intermittently failing test, diagnosed to a real cause rather than retried until it passes.

Category: Test coverage and flaky tests
Source: https://letsship.ai/use-cases/fix-a-flaky-test
Published: 2026-08-25

## Goal

Find why one test fails intermittently and fix the cause, or quarantine it with the cause documented.

## Acceptance criteria

- The test passes across a repeated run in CI, not just once
- The cause is named in the description: timing, ordering, shared state, or a real defect
- No retry wrapper is added to make it pass
- If the cause is a real defect, that is filed rather than hidden

## What lands as proof

A repeated CI run passing, plus a written cause. A retry count is not a fix and is not accepted here.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Fix the flake in {test}

Description: Find why one test fails intermittently and fix the cause, or quarantine it with the cause documented.

Acceptance criteria:
- The test passes across a repeated run in CI, not just once
- The cause is named in the description: timing, ordering, shared state, or a real defect
- No retry wrapper is added to make it pass
- If the cause is a real defect, that is filed rather than hidden

Before you create the issue, look at recent CI runs for this repository and pick the test that fails most often. Replace {test} with it and link a failing run.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: find why one test fails intermittently and fix the cause, or quarantine it with the cause documented. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means passes across repeated runs in CI, cause named in the description, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

None is required before the run starts. Every claim this ticket makes can be checked by machine, so the agent works straight through and a person reviews the finished pull request like any other.