port-upstream - SKILL.md Agent Skill

name: port-upstream description: "Analyzes upstream fork PR changes and ports selected items into the local branch. Use when checking upstream PRs, porting upstream changes, or planning selective upstream integration." when_to_use: "port upstream, upstream PR, check upstream, upstream changes, upstream fork, bring changes from upstream" user-invocable: true argument-hint: "[release_tag | compare_url | pr_url]" allowed-tools: ["Agent", "Bash", "Read", "Glob", "Grep"]

Step 1. Derive the canonical diff (do this BEFORE spawning any agent)

The input to analysis must be a git diff between two tags (or two commits) — not release-notes prose. Release notes are summaries; the diff is ground truth.

1a. Resolve the tag range

From the user's input, identify the upstream repo and the two endpoints:

HEAD tag — the release/PR being evaluated (e.g. v4.4.0)
BASE tag — the previous release tag on the same upstream branch (e.g. v4.3.0), or whatever tag we last successfully ported up to

If only a release URL is given, infer BASE from the upstream's tag list (gh release list --repo <upstream> --limit 5) — the immediately preceding semver tag.

1b. Fetch the diff via one of these (cheapest first)

# Option A — GitHub compare endpoint (no local fetch needed; works for any public fork)
gh api repos/<owner>/<repo>/compare/<BASE>...<HEAD> \
  --jq '.files[] | {filename, status, additions, deletions, patch}' > /tmp/upstream-diff.json

# Option B — local git (if upstream is wired as a git remote)
git fetch upstream --tags
git diff upstream/<BASE>..upstream/<HEAD> -- ':!*.lock' ':!bin/' ':!*.min.*'

Exclude generated artifacts (bin/, lock files, minified output) — they're noise.

1c. Spawn the Explore agent on the diff

Pass the diff file path (not the release URL) as the agent's primary input. Brief:

Classify each changed hunk: new feature / bug fix / doc / generated artifact.
For each substantive change, produce a one-line summary plus the file:line citation from the upstream diff.
For every item the agent classifies as "already in local", it must produce one of the evidence forms in Verification Rules below. A bare commit-hash citation is not sufficient and must be rejected.
Translate any non-English content to English (see Rules).

Why a diff, not release notes

Release notes are prose summaries written by the upstream author. They invite subject-line matching — "upstream said X, local commit says X, must be the same." That heuristic produces false-positive merge claims. Diffs eliminate the abstraction: the hunks either are or are not in the working tree, no interpretation needed.

Step 2. Build the harness plan from the finding

Based on what we found in Step 1, write a plan through /harness-plan
If there is nothing worth porting, just tell user.

Verification Rules — "is this change already in local?"

This skill exists in a fork of an upstream repo. After git fetch upstream, every commit upstream pushes is reachable by hash from the local repo, even if no local branch points at it. This makes hash-based "proof" unreliable.

Forbidden checks (do not use as proof of local presence)

git show <hash> — works on any fetched object, including unmerged upstream commits.
git log --oneline | grep <hash> — same problem; the hash is in the object DB, not necessarily on master.
Subject-line matching ("upstream commit says X, local commit says X" → "we have it") — heuristic only, never proof.

Required checks (use one — pick the cheapest)

Working-tree symbol grep (preferred). Pick a unique symbol the upstream change introduces — a function name, variable name, regex literal, error string — and grep the working tree:
```
grep -rn 'headingTaskRe' .   # if it's missing, the change is not present, full stop
```
Branch reachability (when only a hash is available). Confirm the cited commit is reachable from master:
```
git branch --contains <hash>   # empty output = not merged, ignore the citation
```

Default question

When verifying "is this in local?", default the framing to "what would prove this is missing?" — not "what would prove it's present?". Confirmation bias is the recurring failure mode in port reviews; refutation-first framing is the cheapest counter.

Rules

If changes are in Japanese or non English, translate to English
One verifier, not chained reviewers. Layered second-opinions amplify bad evidence — if the first agent's check is wrong, a reviewer checking the same way will reach the same wrong conclusion.