chore(skill): document why each git-log path is watched

Replace the stale reference to the upstream "client side changes" workflow
with an inline explanation of what each watched path can affect on the
Java side, so the rolling instructions stand on their own.

Author: yury-s

.claude/skills/playwright-roll/SKILL.md

@@ -7,10 +7,45 @@ Help the user roll to a new version of Playwright.
 ROLLING.md contains general instructions and scripts.
 
 Start with running ./scripts/roll_driver.sh to update the version and generate the API to see the state of things.
-Afterwards, work through the list of changes that need to be backported.
-You can find a list of pull requests that might need to be taking into account in the issue titled "Backport changes".
-Work through them one-by-one and check off the items that you have handled.
-Not all of them will be relevant, some might have partially been reverted, etc. - so feel free to check with the upstream release branch.
+Afterwards, walk through the upstream changes that affect the Java client and port the relevant ones.
+
+## Determining what to port
+
+List the upstream commits that touched a client-relevant path since the last release. The paths cover everything that can change the public Java surface or the wire protocol:
+
+- `docs/src/api/` — the source of truth for `api.json`. Method/option additions, removals, and `langs:` filter changes flow from here.
+- `packages/playwright-core/src/client/` — the JS client implementation that the Java client mirrors.
+- `packages/isomorphic/` — selector engines, locator generation/parsing, and aria-snapshot logic shared between client and server. Changes here can affect client-side helpers like `getByRoleSelector`.
+- `packages/playwright/src/matchers/matchers.ts` — assertion-method definitions. Changes here usually correspond to new options on `LocatorAssertions` / `PageAssertions`.
+- `packages/protocol/src/protocol.yml` — the wire protocol schema. Method/event additions, parameter renames, and result-shape changes affect what the Java `*Impl` classes need to send/receive.
+
+```bash
+cd ~/playwright
+PREV_TAG=$(git tag | grep -E '^v1\.[0-9]+\.[0-9]+$' | sort -V | tail -1)  # e.g. v1.59.1
+git log "$PREV_TAG"..HEAD --oneline -- \
+  'docs/src/api/' \
+  'packages/playwright-core/src/client/' \
+  'packages/isomorphic/' \
+  'packages/playwright/src/matchers/matchers.ts' \
+  'packages/protocol/src/protocol.yml'
+```
+
+Walk that list top-to-bottom (oldest-first is easier — newest is at top, so reverse). For each commit:
+1. Read the commit (`git show <sha>`) to see what client/protocol/docs changed.
+2. If it's JS-internal (bundling, dispatcher conventions, electron, mcp, dashboard, trace-viewer, test-runner) — skip.
+3. If it touches `docs/src/api/` or types, check `langs:` annotations — features marked `langs: js`/`langs: js, python` don't apply to Java.
+4. If it adds/changes a public API method or option that applies to Java, port it. The api.json regenerated by `roll_driver.sh` already contains the new types/options, so the generated Java interfaces usually pick them up automatically — what's typically missing is the `*Impl` wiring.
+5. Watch for follow-up reverts — a "feat: X" commit might be undone by a later "Revert X". Check whether the change still exists in HEAD before porting.
+6. Maintain a running notes file (e.g. `/tmp/roll-notes.md`) listing each upstream PR as ported / skipped / verified-already-supported, with a one-line reason. This file becomes the body of the eventual PR.
+
+## What to include in the rolling PR
+
+- Driver version bump
+- Generated interface diffs from `roll_driver.sh`
+- `*Impl` wiring for each ported feature
+- Generator updates (import lists, special-cases) if new types appeared
+- A small test per new public API surface — listener for new events, basic call for new methods, regression for changed return types
+- PR description: list each upstream PR ported, each skipped (with reason), and each verified-already-supported
 
 Rolling includes:
 - updating client implementation to match changes in the upstream JS implementation (see ../playwright/packages/playwright-core/src/client)
@@ -164,5 +199,4 @@ Branch naming for issue fixes: `fix-<issue-number>`
 
 ## Tips & Tricks
 - Project checkouts are in the parent directory (`../`).
-- When updating checkboxes, store the issue content into /tmp and edit it there, then update the issue based on the file
 - use the "gh" cli to interact with GitHub