---
name: release
description: Orchestrate an Open Notebook release — changelog audit, risk-based A/B/C test matrix, Docker image gate (fresh + upgrade), fix loop via PRs, cut, publication with credits, retro. Use when preparing, testing, cutting or publishing a release.
---

# Open Notebook Release Orchestrator

You are conducting a release of Open Notebook, reproducing the process
established in v1.11.0. The **source of truth for the process** is
`.github/RELEASE_PROCESS.md` — read it first. This skill adds the
orchestration order, the exact commands, and the human gates.

**Ground rules for the whole run:**

- The release happens in a **single session**. Track phases with the task
  tools (TaskCreate/TaskUpdate) so the owner sees progress.
- Every repo change goes through a **PR** (branch → PR → CI + cubic → merge).
  Never push to main. Confirm the owner authorizes you to merge your own PRs
  when clean; otherwise hand merges to them.
- Interact in the owner's language; write code, commits and docs in English.
- Read `${CLAUDE_SKILL_DIR}/gates.md` NOW — it defines what you may do
  autonomously and what requires an explicit GO.

## Phase 0 — Scope and changelog audit

1. `git fetch --tags` · find the last release tag and `gh release list`.
2. List everything merged since: `git log <last-tag>..origin/main --oneline`.
3. Audit the CHANGELOG `[Unreleased]` section against that list. Convention:
   entries reference the **issue** number when one exists, the PR number
   otherwise. Close every gap via PR.
4. Check open Dependabot alerts (`gh api repos/{owner}/{repo}/dependabot/alerts?state=open`)
   — a security-themed release with open highs is incoherent. Triage them
   into the fix loop or document acceptance.

## Phase 1 — Risk-based test matrix

Read `${CLAUDE_SKILL_DIR}/test-matrix.md` and instantiate it against the
actual release diff. Classify each change: what can it break, for whom,
which bucket (A/B/C) verifies it. **Refine the matrix with the owner before
executing** — they decide bucket-B investments and own bucket C.

## Phase 2 — Execute bucket A

Run in parallel where possible:

- `uv run pytest tests/` · `ruff check .` · `uv run python -m mypy .` (all three
  are required CI gates since the July 2026 cleanup; mypy must exit 0)
- Frontend: `npm run lint`, `npm run test`, `npm run build` (production build;
  a stale `node_modules` produces false build failures — `npm ci` first if so)
- The **smoke-e2e agent** against the local dev stack (start it: database →
  api → worker → frontend; check ports are free first — another project may
  hold 3000/8000: identify the owner via `lsof` + process cwd, never kill
  blind; the frontend runs fine on `PORT=3001 npm run dev` — pass the URL to
  the smoke agent. Also note the dev `.env` may point at a standalone
  SurrealDB, not the repo-compose one)
- **Dev-DB leak check**: snapshot per-table record counts (at least
  credentials) before and after the backend suite — a diff means a test is
  writing to the live database (caught 48 leaked credentials in v1.12.0)
- The **targeted probes** from the matrix (legitimate-use regression checks
  for security changes)

## Phase 3 — Image gate + bucket C kickoff

- `make docker-build-local`, then `make release-test TAG=<ver> OLD_TAG=<prev>`
  (pull the genuine previous tag first — see gotchas in RELEASE_PROCESS.md).
- Hand the owner their bucket-C checklist (from the matrix) so they test in
  parallel — do not leave them as the bottleneck at the end.

## Phase 4 — Fix loop

For each finding: reproduce → root-cause → focused PR with regression tests →
CI + cubic → merge (per gates.md). Apply the re-test policy from
RELEASE_PROCESS.md after each merge. Pre-existing bugs that are not release
regressions become backlog issues (ask the owner before creating issues).
Verify UI fixes in the real browser (Playwright) before opening the PR.

## Phase 5 — Cut

1. Cut PR off updated main: bump `pyproject.toml`, date the changelog section.
2. After merge: `make tag`.
3. Rebuild the image from final main and **re-run the image gate** against it.
4. Push version images via CI:
   `gh workflow run build-and-release.yml --ref main -f push_latest=false`
   and watch the run. (Local `make docker-push` needs `docker login`.)
5. Verify the pushed manifests (see `${CLAUDE_SKILL_DIR}/runbook.md`).

## Phase 6 — Pushed-image verification (human gate)

Offer the owner a browsable RC stack on this machine:
`make release-stack TAG=<ver> [DUMP=<dump>]` — with a copy of their dev data
for realism (export command in the runbook). Support them through it; findings
go back to Phase 4. **Do not proceed without their GO.**

## Phase 7 — Publish (human gate)

1. Draft release notes per `${CLAUDE_SKILL_DIR}/comms-templates.md` — the
   **Thanks section is mandatory**; collect every contributor with the
   commands in the template. Show the owner for review.
2. With their explicit GO: `gh release create v<ver> --title ... --notes-file ... --latest`.
   Publication triggers CI to push `v1-latest` — watch it, then verify the
   latest manifests (runbook).
3. Mark shipped issues with the `released` label (ask before mass-labeling).
4. Deliver the Discord post text (the owner posts it).

## Phase 8 — Cleanup

`make release-stack-down`, remove temp dumps/data dirs, stop watchers, ensure
`git status` is clean on main and no test containers remain.

## Phase 9 — Retro (always runs)

Ask the owner: *"what should improve in this process?"* — and apply the
accepted improvements **now**: edit `.github/RELEASE_PROCESS.md`,
`scripts/release-test/*`, and this skill's files while context is fresh.
New gotchas discovered during the run go into RELEASE_PROCESS.md's Known
Gotchas via the same PR flow.