Comparison Base Resolution

Comparison Base Resolution

Use this skill when another workflow needs to compare a branch or working tree with the branch it is intended to merge into. This skill resolves the comparison refs and commit; the caller decides what paths and endpoint to diff.

Inputs

• $REVIEW_REF: the commit being reviewed. Default to HEAD.

Set $IS_LOCAL_REVIEW=true when the input is HEAD, or when a named local branch is the currently checked-out branch; otherwise set it to false. Callers use this explicit value to decide whether workspace changes belong to the review.

For HEAD or a named review branch, record $REVIEW_BRANCH when the ref identifies a local branch. Resolve its published destination using Git's push precedence: branch.<name>.pushRemote, then remote.pushDefault, then the branch's configured upstream remote. Store the remote name or URL usable by Git as $REVIEW_FETCH_SOURCE, normalize that remote's GitHub URL to owner/repository as $REVIEW_REPOSITORY, and store the remote branch name as $REVIEW_HEAD_BRANCH. Keep these values distinct: Git commands consume $REVIEW_FETCH_SOURCE, while GitHub PR metadata uses $REVIEW_REPOSITORY. The published branch may have a different name from the local branch. Without any configured destination, inspect configured remotes for an exact $REVIEW_BRANCH match and derive all three values; ask the user if multiple remotes match. A detached HEAD, commit input, or unpublished local branch may leave the published identity unset.

For a named review branch, prefer an exact local branch and set REVIEW_REF=refs/heads/$REVIEW_BRANCH. If there is no local branch and exactly one remote matches, set $REVIEW_FETCH_SOURCE to that remote, derive $REVIEW_REPOSITORY from its URL, set $REVIEW_HEAD_BRANCH=$REVIEW_BRANCH, fetch the branch into a dedicated ref, and use that ref as $REVIEW_REF:

git fetch --no-tags "$REVIEW_FETCH_SOURCE" "+refs/heads/$REVIEW_BRANCH:refs/comparison/head"
REVIEW_REF=refs/comparison/head

If the branch is absent, ask the user for another review ref. If it exists on multiple remotes and has no configured upstream or push remote, ask the user which remote to assign to $REVIEW_FETCH_SOURCE, derive $REVIEW_REPOSITORY, then fetch it as shown above. Finally, set $REVIEW_OID:

REVIEW_OID=$(git rev-parse "$REVIEW_REF")

Step 1: Resolve the target branch

Resolve an open PR using the following sources in order, stopping as soon as one source produces exactly one validated match. Do not query later sources after a match is resolved.

1. Prefer active PR metadata already available from the editor's PR integration. Verify its head repository and branch match $REVIEW_REPOSITORY and $REVIEW_HEAD_BRANCH when those values are known. Its published head must also match $REVIEW_OID or be an ancestor of a locally-ahead $REVIEW_REF.
2. If no match was resolved and $REVIEW_REPOSITORY and $REVIEW_HEAD_BRANCH are known, query open PRs by branch. gh pr list --repo <candidate-base-repository> --state open --head "$REVIEW_HEAD_BRANCH" --json url,state,baseRefName,headRefName,headRefOid,headRepository is convenient; query GitHub repositories named by configured remotes, including microsoft/FluidFramework, one at a time and stop after a validated match. Validate headRepository.nameWithOwner against $REVIEW_REPOSITORY. This branch query lets a locally-ahead commit resolve its published PR.
3. If still unresolved, query the GitHub commit-to-PR API (repos/{owner}/{repo}/commits/$REVIEW_OID/pulls) for the same candidate repositories, one at a time, and stop after a validated match. Treat HTTP 404 or 422 as no candidates and continue; locally-ahead or unpublished commits may not exist in the queried repository.

From any source, read the PR state and URL, base repository and branch, and head repository, branch, and SHA. Only accept open PRs whose head repository and branch match the known review identity and whose head SHA matches $REVIEW_OID or is its ancestor.

Do not rely on bare gh pr view, bare gh repo view, or an unqualified repository context. These are ambiguous in fork checkouts; pass an explicit PR URL or --repo owner/repository. If multiple open PRs match, ask the user which PR to use.

For a matching PR, set:

• $TARGET_SOURCE to its base repository clone URL