Skip to content

feat(skills): add /release-recovery skill for npm/repo release desync #36565

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Martin Hochel (Hotell) merged 2 commits into from
Aug 24, 2026
+646 −13
Merged

feat(skills): add /release-recovery skill for npm/repo release desync #36565

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c5172c3
feat(skills): add /release-recovery skill for npm/repo release desync
Hotell Aug 12, 2026
f836369
fix(check-release-sync): don't report registry failures as unpublished
Hotell Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
246 changes: 246 additions & 0 deletions .agents/skills/release-recovery/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,246 @@
---
name: release-recovery
description: >-
Diagnose and repair a release that published packages to npm but failed to push the version bumps and changelogs back to the repository. Accepts an optional failed Azure DevOps pipeline run URL for context. Always presents a read-only diagnosis first and requires explicit approval before changing branches, commits or pull requests.
disable-model-invocation: true
argument-hint: '[pipeline-url] [--ref upstream/master] [--remote upstream]'
allowed-tools: Bash Read Grep Glob
---

# Release Recovery

Repair the desync a failed release leaves behind: packages are live on npm, but the repository still
has the old versions.

npm publishes are irreversible, so **npm is the source of truth**. Recovery always means moving the
repository forward to match the registry — never the other way round.

The default operation is read-only. Do not create branches, commits or pull requests until the user
explicitly approves a proposed plan.

## Scope

Recovery restores **version bumps and changelogs**. It does **not** recreate release git tags:

- A recovery commit is not the commit the release was built from, so tags created against it would
point at the wrong history — worse than having no tag.
- A single release spans dozens of packages (a v9 release touches ~90), so bulk tag creation is
noisy and effectively unreviewable.
- Tags are not load-bearing for consumers; npm is what they install from.

Missing tags can still be _reported_ for awareness with `--check-tags` on the diagnostic, but they
are informational. If tags are genuinely needed for a specific release, create them deliberately as
a separate, explicitly-approved task.

## When to use

- A release pipeline failed after the "Publishing" step (typically a git push `403`/auth failure).
- A release was published to npm deliberately without pushing (a forced release that skips the git
push).

## Defaults

| Argument | Default | Purpose |
| -------------- | --------------------------------------- | --------------------------------------------------- |
| `pipeline-url` | none | Failed ADO run, used only for context and reporting |
| `--ref` | the release branch on the remote | Git ref whose versions are compared against npm |
| `--remote` | remote pointing at `microsoft/fluentui` | Used for fetching and pushing |

Resolve `--remote` by inspecting `git remote -v` for the one pointing at `microsoft/fluentui`. It is
often `upstream` in a fork checkout, so never assume `origin`.

## Workflow

### Step 1 — Establish context

Confirm tooling and record the starting ref so it can be restored later:

```bash
gh auth status
git remote -v
git status --porcelain
```

Record `START_REF` (`git symbolic-ref --quiet --short HEAD || git rev-parse HEAD`).

If the working tree has uncommitted changes, stop and ask the user to deal with them. Recovery
rewrites `package.json`, changelog and lockfile content and must not mix with unrelated edits.

Fetch the release branch so the comparison is not made against a stale checkout:

```bash
git fetch "$REMOTE" master
```

### Step 2 — Read the failed pipeline (optional)

If a pipeline URL was supplied, use it for context only. Parse the organization, project and build id
from a URL of the form
`https://dev.azure.com/<org>/<project>/_build/results?buildId=<id>`.

```bash
az pipelines runs show --org "https://dev.azure.com/$ORG" --project "$PROJECT" --id "$BUILD_ID"
```

Useful signals in the log:

- `Publishing - <pkg>@<version>` followed by `Published!` — packages that reached npm.
- `Something went wrong with publishing! Manually update these package and versions:` — beachball's
own list of what needs recovering.
- `remote: ... forbids access via a personal access tokens (classic)` or
`The requested URL returned error: 403` — the push failed on auth, which is the usual cause.

Treat all of this as **corroboration only**. If `az` is not authenticated or the run has been purged,
say so and continue: the diagnosis in Step 3 does not depend on it.

### Step 3 — Diagnose (read-only)

Run the sync check against the up-to-date release branch:

```bash
node -r ./scripts/ts-node/src/register ./scripts/executors/src/check-release-sync.ts \
--remote "$REMOTE" --ref "$REMOTE/master"
```

Add `--json` when the output needs parsing.

Always pass `--ref` pointing at the remote release branch. Comparing the working tree of a stale
checkout reports every package released since as a false desync.

The check classifies each public package:

| Status | Meaning | Action |
| ------------- | -------------------------------------------------------------------- | ---------------- |
| `in-sync` | repo and npm agree | none |
| `npm-ahead` | published, but the repo never recorded the bump | recover versions |
| `repo-ahead` | repo is newer than npm's `latest` (unreleased work, prerelease tags) | none — benign |
| `unpublished` | never released | none |

Only `npm-ahead` requires recovery.

### Step 4 — Present the plan and get approval

```markdown
## Release recovery plan

- Pipeline: <url or "not supplied">
- Remote: upstream
- Compared against: upstream/master
- Version desync: 2 package(s)

### Version desync

| Package | Repo | npm |
| --------------- | ------- | ------- |
| @fluentui/react | 8.125.6 | 8.125.7 |

### Proposed actions

1. Regenerate bumps + changelogs from the pending change files
2. Verify the result matches npm exactly
3. Open a recovery PR

Release tags are not recreated - see the skill's Scope section.
```

Stop here if there is no `npm-ahead` drift. Otherwise ask the user to approve or cancel. Never treat
invoking the skill as approval to mutate anything.

### Step 5 — Recover versions

Skip this step when nothing is `npm-ahead`.

Create a branch from the current release branch:

```bash
git switch -c "release-recovery/$(date -u +%Y%m%d-%H%M%S)" "$REMOTE/master"
yarn install
```

Regenerate the release locally. The change files consumed by the failed run are still in the repo
(their deletion was never committed), so beachball reproduces the same bumps and changelogs:

```bash
yarn beachball bump --config scripts/beachball/src/<release>.config.js
```

Pick the config matching the failed pipeline:

| Release | Config | Pipeline |
| -------------- | -------------------------------------------------------- | -------------------------------------------- |
| v8 | `scripts/beachball/src/release-v8.config.js` | `azure-pipelines.release.yml` |
| v9 (vNext) | `scripts/beachball/src/release-vNext.config.js` | `azure-pipelines.release-vnext.yml` |
| web-components | `scripts/beachball/src/release-web-components.config.js` | `azure-pipelines.release.web-components.yml` |
| headless | `scripts/beachball/src/release-headless.config.js` | `azure-pipelines.release.headless.yml` |
| tools | `scripts/beachball/src/release-tools.config.js` | `azure-pipelines.release.tools.yml` |

`beachball bump` only writes files — it does **not** commit, tag or push. Tagging and pushing live
exclusively in beachball's `bumpAndPush`, which is reachable only from the `publish` command.
Verified empirically against `3.0.0-alpha.7`: a full `bump` run changed 123 files and created 0 tags,
0 commits and 0 branches.

It does **not** run the `precommit` hook either (that also only runs on the push path), so apply the
same fixups a real release would. Keep this in sync with `hooks.precommit` in
[scripts/beachball/src/shared.config.ts](../../../scripts/beachball/src/shared.config.ts):

```bash
yarn nx g @fluentui/workspace-plugin:dependency-mismatch
yarn nx g @fluentui/workspace-plugin:normalize-package-dependencies
yarn install --mode=update-lockfile
```

Expect `bump` to consume **more change files than it bumps packages**. `type: "none"` change files
are deleted without producing a version bump — that is normal, and matches what a real release does.

**Verify before committing.** Re-run the sync check against the working tree:

```bash
node -r ./scripts/ts-node/src/register ./scripts/executors/src/check-release-sync.ts --remote "$REMOTE"
```

Every previously `npm-ahead` package must now be `in-sync`. If any version overshoots npm, extra
change files landed after the failed release, so a plain replay is not correct — stop, report the
mismatch, and let the user decide. Never hand-edit versions to force a match.

Commit and open a PR:

```bash
git add -A
git commit -m "release: applying package updates (manual recovery)"
git push "$PUSH_REMOTE" HEAD
gh pr create --repo microsoft/fluentui --base master \
--title "release: applying package updates (manual recovery)" \
--body-file "$PR_BODY_FILE"
```

The PR body must state which pipeline failed and that the packages are already on npm.

### Step 6 — Restore and report

```bash
git switch "$START_REF"
```

Report:

- Packages recovered, with repo and npm versions.
- Recovery PR URL.
- Anything skipped, with the reason.
- A reminder to fix the underlying cause — usually rotating the GitHub PAT in the
`Github and NPM secrets` variable group — since the next release fails identically otherwise.

## Guardrails

- Always diagnose and obtain approval before mutating anything.
- Never unpublish, deprecate or re-publish an npm package to "fix" a mismatch. npm is the source of
truth; the repository moves to match it.
- Never hand-edit versions to force agreement with npm. Regenerate with beachball so changelogs and
dependency ranges stay consistent, and stop if the result disagrees.
- Never commit directly to `master`; always go through a PR.
- Never create or push release tags as part of recovery. They would point at a commit the release was
not built from, and a single release spans dozens of packages.
- Never assume `origin` points at `microsoft/fluentui` — resolve the remote explicitly.
- Never trust a diagnosis made against a stale checkout; always compare against the fetched release
branch.
- Never request or print a GitHub or npm token.
- Do not proceed when the working tree has uncommitted changes.
1 change: 1 addition & 0 deletions .claude/skills/release-recovery/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
@../../../.agents/skills/release-recovery/SKILL.md
27 changes: 14 additions & 13 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,19 +91,20 @@ state.root.className = mergeClasses(

## Skills (Slash Commands)

| Skill | Command | Purpose |
| -------------------- | -------------------------- | ------------------------------------------------------------------------- |
| `v9-component` | `/v9-component Name` | Scaffold a new v9 component with all required files |
| `headless-component` | `/headless-component Name` | Author an unstyled v9 primitive with state attributes, tests, and stories |
| `change` | `/change` | Create beachball change file from current diff |
| `lint-check` | `/lint-check [pkg]` | Run lint, parse errors, and auto-fix common issues |
| `token-lookup` | `/token-lookup val` | Find the design token for a hardcoded CSS value |
| `package-info` | `/package-info pkg` | Quick lookup: path, deps, owner, tests, structure |
| `visual-test` | `/visual-test Name` | Visually verify a component via Storybook + playwright-cli |
| `review-pr` | `/review-pr #123` | Review a PR with confidence scoring and category checks |
| `triage-issues` | `/triage-issues` | Walk the Needs-Triage queue and recommend labels/assignee |
| `dependabot-rollup` | `/dependabot-rollup` | Dry-run and optionally roll up at most 11 Dependabot patch/minor PRs |
| `assign-prs` | `/assign-prs` | Assign reviewers to the team review queues by area and current load |
| Skill | Command | Purpose |
| -------------------- | ---------------------------------- | ------------------------------------------------------------------------- |
| `v9-component` | `/v9-component Name` | Scaffold a new v9 component with all required files |
| `headless-component` | `/headless-component Name` | Author an unstyled v9 primitive with state attributes, tests, and stories |
| `change` | `/change` | Create beachball change file from current diff |
| `lint-check` | `/lint-check [pkg]` | Run lint, parse errors, and auto-fix common issues |
| `token-lookup` | `/token-lookup val` | Find the design token for a hardcoded CSS value |
| `package-info` | `/package-info pkg` | Quick lookup: path, deps, owner, tests, structure |
| `visual-test` | `/visual-test Name` | Visually verify a component via Storybook + playwright-cli |
| `review-pr` | `/review-pr #123` | Review a PR with confidence scoring and category checks |
| `triage-issues` | `/triage-issues` | Walk the Needs-Triage queue and recommend labels/assignee |
| `dependabot-rollup` | `/dependabot-rollup` | Dry-run and optionally roll up at most 11 Dependabot patch/minor PRs |
| `assign-prs` | `/assign-prs` | Assign reviewers to the team review queues by area and current load |
| `release-recovery` | `/release-recovery [pipeline-url]` | Diagnose and repair a release that published to npm but failed to push |

## Package Layout

Expand Down
Loading
Loading