From 729eece99dc43ce89855a235a895c64b254930e0 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 16 Jul 2026 21:49:26 +0200 Subject: [PATCH 1/3] docs(merge-gate): triage a one-shard-red suite as flake vs. real regression MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A /retro session (2026-07-16) found a red `E2E (1/4)` dismissed as a boot flake twice — correct once, but the second run was a real regression. Add a section on reading the shard's first error: a stack-boot/health-check line at the top means collateral failures below (infra flake, rerun); the same specs failing across all shards means a real bug. Notes the Playwright `locator.check: Test timeout` = actionability tell for a broken hit target. Signed-off-by: Sebastian Mendel --- skills/git-workflow/references/merge-gate-watcher.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/skills/git-workflow/references/merge-gate-watcher.md b/skills/git-workflow/references/merge-gate-watcher.md index 3f9d352..4b47b4c 100644 --- a/skills/git-workflow/references/merge-gate-watcher.md +++ b/skills/git-workflow/references/merge-gate-watcher.md @@ -12,6 +12,15 @@ Classify every failing check BEFORE reacting: | **Soft, self-healing** | `codecov/*` while sibling jobs still run (partial uploads) | Ignore while `pending > 0`; if persisting after completion: one full `gh run rerun ` | | **Soft, structural** | SonarCloud PR gate on refactor PRs | Introspect before deciding (below) | +## One shard red in a sharded suite: flake vs. real regression + +When one of N test shards fails, read its **first** error before you reach for a rerun — whether the Hard-class failure above is a flake or a real bug turns on it: + +- **Infra flake** — the first error is a stack-boot / health-check line (`App failed to start within timeout`, DB-not-ready, a 5xx from the app root). Every assertion failure below it is collateral: there was no app to talk to. Only that one shard is red; the siblings pass. Reaction: one `gh run rerun --failed` (a rebase + push also re-triggers a clean run). +- **Real regression** — the *same* spec(s) fail **across all shards deterministically**, and the first error is an assertion (or an actionability timeout), not a boot line. A regression in shared code does not politely confine itself to one shard. + +Playwright tell: `locator.check` / `locator.click: Test timeout` is an **actionability** failure — the element never became visible / stable / hit-testable — usually a CSS or DOM change that broke a hit target. Treat it as a real regression to investigate even when it surfaces on a single shard, not as a flake to rerun. (Seen: a `.field-check-row` restyle moved a label out of the node a spec located by, so `getByText`-anchored `.check()` hung 30s — red on shard 1 only, looked exactly like a boot flake, was a real DOM regression.) + ## Sonar gate introspection Never merge on a red Sonar gate without knowing *why* it is red: From 746fc6c92aa32b965f82d6267f3c30e9e4f933f2 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 16 Jul 2026 21:49:26 +0200 Subject: [PATCH 2/3] docs(advanced-git): read a file as committed on another branch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add `git show :` for inspecting a file's committed content on another ref without checkout. A /retro session (2026-07-16) hit a phantom "file was modified" after a branch switch — the on-disk copy reflected the landed branch, not the one being reasoned about. Reading from the object store is authoritative. Signed-off-by: Sebastian Mendel --- .../git-workflow/references/advanced-git.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/skills/git-workflow/references/advanced-git.md b/skills/git-workflow/references/advanced-git.md index 02220d3..6aff558 100644 --- a/skills/git-workflow/references/advanced-git.md +++ b/skills/git-workflow/references/advanced-git.md @@ -843,6 +843,28 @@ Use `--diff-filter=ACMR` (not just `AM`) so renames and copies into a guarded path are caught. Verify pathspec support empirically before swapping one command for the other — the failure mode is silent, not loud. +## Reading a File As It Is Committed on Another Branch + +To see what a file *actually contains on another branch or ref* — without +switching to it — read it from the object store: + +```bash +git show : # e.g. git show origin/main:src/App.tsx +git show : +git show : +``` + +Use this instead of trusting the working-tree copy right after a `git checkout`. +A branch switch swaps every file on disk, so the on-disk copy (and any editor or +harness "file was modified" notice fired by the switch) reflects the branch you +landed on, not the one you were reasoning about — chasing that phantom "edit" is +a real time sink. `git show :` answers "what's committed there?" +authoritatively; reserve the working tree for "what's staged/unsaved here now?". + +For a whole-tree comparison across branches without checkout, use +`git diff -- ` (or `git diff ...` for +the merge-base–relative diff). + ## Troubleshooting ### Common Issues From 824f8d83d141cd8ab07d5cfefcd98829f3311674 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 16 Jul 2026 22:25:48 +0200 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20scop?= =?UTF-8?q?e=20diff=20to=20a=20file,=20soften=20regression=20definition?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Gemini review on #101: `git diff -- ` compares a file, not the whole tree — reword and add `-- ` to the three-dot example. And the "real regression fails across all shards" line tensioned with the single-shard Playwright case — mark it the typical case, with the Playwright exception. Signed-off-by: Sebastian Mendel --- skills/git-workflow/references/advanced-git.md | 6 +++--- skills/git-workflow/references/merge-gate-watcher.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/git-workflow/references/advanced-git.md b/skills/git-workflow/references/advanced-git.md index 6aff558..cb315d3 100644 --- a/skills/git-workflow/references/advanced-git.md +++ b/skills/git-workflow/references/advanced-git.md @@ -861,9 +861,9 @@ landed on, not the one you were reasoning about — chasing that phantom "edit" a real time sink. `git show :` answers "what's committed there?" authoritatively; reserve the working tree for "what's staged/unsaved here now?". -For a whole-tree comparison across branches without checkout, use -`git diff -- ` (or `git diff ...` for -the merge-base–relative diff). +To compare a file across branches without checkout, use +`git diff -- ` (or `git diff ... -- ` +for the merge-base–relative diff). ## Troubleshooting diff --git a/skills/git-workflow/references/merge-gate-watcher.md b/skills/git-workflow/references/merge-gate-watcher.md index 4b47b4c..c0b0eaf 100644 --- a/skills/git-workflow/references/merge-gate-watcher.md +++ b/skills/git-workflow/references/merge-gate-watcher.md @@ -17,7 +17,7 @@ Classify every failing check BEFORE reacting: When one of N test shards fails, read its **first** error before you reach for a rerun — whether the Hard-class failure above is a flake or a real bug turns on it: - **Infra flake** — the first error is a stack-boot / health-check line (`App failed to start within timeout`, DB-not-ready, a 5xx from the app root). Every assertion failure below it is collateral: there was no app to talk to. Only that one shard is red; the siblings pass. Reaction: one `gh run rerun --failed` (a rebase + push also re-triggers a clean run). -- **Real regression** — the *same* spec(s) fail **across all shards deterministically**, and the first error is an assertion (or an actionability timeout), not a boot line. A regression in shared code does not politely confine itself to one shard. +- **Real regression** — *typically* the same spec(s) fail **across all shards deterministically**, and the first error is an assertion (or an actionability timeout), not a boot line. A regression in shared code does not politely confine itself to one shard. (The Playwright case below is the exception — a real regression that can surface on a single shard.) Playwright tell: `locator.check` / `locator.click: Test timeout` is an **actionability** failure — the element never became visible / stable / hit-testable — usually a CSS or DOM change that broke a hit target. Treat it as a real regression to investigate even when it surfaces on a single shard, not as a flake to rerun. (Seen: a `.field-check-row` restyle moved a label out of the node a spec located by, so `getByText`-anchored `.check()` hung 30s — red on shard 1 only, looked exactly like a boot flake, was a real DOM regression.)