| 1 | --- |
| 2 | name: fix-integration |
| 3 | description: Fix a g1t pull request that failed when the merge queue tested it together with other pull requests (an integration.failed event). Use when g1t reports an integration failure, or a queued pull request was removed from the merge queue because a combined check failed. |
| 4 | argument-hint: "[pull request number]" |
| 5 | allowed-tools: Bash(g1t:*) Bash(git:*) |
| 6 | --- |
| 7 | |
| 8 | # Fix an integration failure |
| 9 | |
| 10 | The merge queue tests pull requests together, in queue order. A pull |
| 11 | request can pass on its own and still fail once another one is merged |
| 12 | with it. g1t then records an `integration.failed` event naming the pull |
| 13 | request it holds responsible, the combination it tested (the pull requests |
| 14 | merged together, in order), the failing check and its link, whether it |
| 15 | bisected the combination to find the culprit, and the suspects when it |
| 16 | could not tell. When nothing was ahead of it, the default branch itself |
| 17 | moved: `landed` lists the pull requests merged into it since your branch |
| 18 | left it, newest first, and one alone is the likely cause. |
| 19 | |
| 20 | Pull request: $ARGUMENTS (if empty, use the current branch's pull request). |
| 21 | |
| 22 | 1. **Read what failed.** `g1t work events --type integration.failed --json` |
| 23 | for the event (narrow it with `--issue N`), and `g1t work context N` for |
| 24 | the issue, which shows the last integration failure, the pull requests |
| 25 | on it and the decisions so far. |
| 26 | 2. **Open the failing check's log** from the event's check link, or with |
| 27 | `g1t run logs --failed` on that run. Find the first real error. |
| 28 | 3. **Read the other pull requests in the combination**, or in `landed` |
| 29 | when the combination is yours alone. |
| 30 | `g1t pr diff OTHER` for each one, and look for what |
| 31 | meets your change: the same function changed two ways, a renamed or |
| 32 | removed name you still use, a migration, a fixture or a test that |
| 33 | assumes the old behaviour. |
| 34 | 4. **Reproduce the tested state locally.** Read the recorded combined commit |
| 35 | and check log first. Check out that exact commit in a separate worktree |
| 36 | when available and run the failing command. Current branch tips may have |
| 37 | changed since the failure; merging them is a new experiment, not a replay. |
| 38 | Preserve ongoing work. Treat suspects as a failing combination, not proof |
| 39 | of a single cause: a failure may need several changes together or be flaky. |
| 40 | 5. **Fix it on your branch.** Change only what the failure needs. If the |
| 41 | right fix belongs in the other pull request, say so on it |
| 42 | (`g1t pr comment OTHER`) instead of working around it, and tell the |
| 43 | person who asked you. |
| 44 | 6. **Push, then queue again.** Push the fix, wait for `g1t pr checks |
| 45 | --watch` to pass, and merge again with `g1t pr merge`, which puts it |
| 46 | back in the queue. |
| 47 | 7. **Leave a record.** `g1t session log --kind note "Integration failure |
| 48 | with #OTHER: CAUSE. Fixed by CHANGE."` so the next person can see why |
| 49 | the change looks the way it does. Include the tested commit and the |
| 50 | reproducing check; distinguish what you observed from your hypothesis. |
| 51 | |
| 52 | If the event says the failure was not bisected and lists several |
| 53 | suspects, check that yours really is one before changing anything: run the |
| 54 | check on your branch with only the default branch merged in. |