diff --git a/skills/git-workflow/references/advanced-git.md b/skills/git-workflow/references/advanced-git.md index 02220d3..cb315d3 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?". + +To compare a file across branches without checkout, use +`git diff -- ` (or `git diff ... -- ` +for the merge-base–relative diff). + ## Troubleshooting ### Common Issues diff --git a/skills/git-workflow/references/merge-gate-watcher.md b/skills/git-workflow/references/merge-gate-watcher.md index 3f9d352..c0b0eaf 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** — *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.) + ## Sonar gate introspection Never merge on a red Sonar gate without knowing *why* it is red: