From 8ce4cb75af4d8068ec464c92f63bcb4a821735ee Mon Sep 17 00:00:00 2001
From: Josh Spicer <23246594+joshspicer@users.noreply.github.com>
Date: Sat, 28 Mar 2026 07:02:02 +0000
Subject: [PATCH] sessions: add sync-upstream built-in skill (#305771)

* feat: add update-branch skill for rebasing session branches

* fix: update description for update-branch skill to clarify usage

* feat: add sync-upstream skill for rebasing session branches
---
 src/vs/sessions/skills/sync-upstream/SKILL.md | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 src/vs/sessions/skills/sync-upstream/SKILL.md

diff --git a/src/vs/sessions/skills/sync-upstream/SKILL.md b/src/vs/sessions/skills/sync-upstream/SKILL.md
new file mode 100644
index 00000000000..ce3f3224cbd
--- /dev/null
+++ b/src/vs/sessions/skills/sync-upstream/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: sync-upstream
+description: Update a stale session branch by rebasing onto the latest origin. Use when the upstream has moved significantly and the session needs to catch up, resolving conflicts by preserving upstream changes and adapting session work to fit.
+---
+<!-- Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior. -->
+
+# Update Branch
+
+Rebase the current session branch onto the latest upstream so the work stays grounded in origin.
+
+## Workflow
+
+1. If there are uncommitted changes, use the `/commit` skill to commit them first.
+2. Fetch the latest upstream and rebase onto it:
+   ```
+   git fetch origin
+   git rebase origin/main
+   ```
+   Use the appropriate base branch if it is not `main`.
+
+## Conflict Resolution
+
+When conflicts arise, **upstream always wins**:
+
+- **Never alter upstream logic, APIs, or patterns** to accommodate session changes.
+- **Adapt session work** to fit the new upstream — rename, restructure, or rewrite as needed while preserving the session's goals.
+- After resolving each conflict, `git add` the files and `git rebase --continue`.
+
+## Validation
+
+After the rebase completes, verify the result still compiles and meets the session's objectives. If session changes no longer make sense against the updated upstream, explain what changed and propose a revised approach.