Final Release Review

Final Release Review

Purpose

Use this skill when validating the latest release candidate commit (default tip of origin/main) for release. It guides you to fetch remote tags, pick the previous release tag, and thoroughly inspect the BASE_TAG...TARGET diff for breaking changes, introduced bugs/regressions, improvement opportunities, and release risks.

The review must be stable and actionable: avoid variance between runs by using explicit gate rules, and never produce a BLOCKED call without concrete evidence and clear unblock actions.

Quick start

1. Ensure repository root: pwd → path-to-workspace/openai-agents-js. 2. Sync tags and pick base (default v*):

   BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*')"

3. Choose target commit (default tip of origin/main, ensure fresh): git fetch origin main --prune then TARGET="$(git rev-parse origin/main)". 4. Snapshot scope:

   git diff --stat "${BASE_TAG}"..."${TARGET}"
   git diff --dirstat=files,0 "${BASE_TAG}"..."${TARGET}"
   git log --oneline --reverse "${BASE_TAG}".."${TARGET}"
   git diff --name-status "${BASE_TAG}"..."${TARGET}"

5. Deep review using references/review-checklist.md to spot breaking changes, regressions, and improvement chances. 6. Capture findings and call the release gate: ship/block with conditions; propose focused tests for risky areas.

Deterministic gate policy

• Default to 🟢 GREEN LIGHT TO SHIP unless at least one blocking trigger below is satisfied.
• Use 🔴 BLOCKED only when you can cite concrete release-blocking evidence and provide actionable unblock steps.
• Blocking triggers (at least one required for BLOCKED):
• A confirmed regression or bug introduced in BASE...TARGET (for example, failing targeted test, incompatible behavior in diff, or removed behavior without fallback).
• A confirmed breaking public API/protocol/config change with missing or mismatched versioning and no migration path (for example, patch release for a breaking change).
• A concrete data-loss, corruption, or security-impacting change with unresolved mitigation.
• A release-critical packaging/build/runtime path is broken by the diff (not speculative).
• Non-blocking by itself:
• Large diff size, broad refactor, or many touched files.
• "Could regress" risk statements without concrete evidence.
• Not running tests locally.
• If evidence is incomplete, issue 🟢 GREEN LIGHT TO SHIP with targeted validation follow-ups instead of BLOCKED.

Workflow

• Prepare
• Run the quick-start tag command to ensure you use the latest remote tag. If the tag pattern differs, override the pattern argument (e.g., '*.*.*').
• If the user specifies a base tag, prefer it but still fetch remote tags first.
• Keep the working tree clean to avoid diff noise.
• Assumptions
• Assume the target commit (default origin/main tip) has already passed $code-change-verification in CI unless the user says otherwise.
• Do not block a release solely because you did not run tests locally; focus on concrete behavioral or API risks.
• Release policy: routine releases use patch versions; use minor only for breaking changes or major feature additions. Major versions are reserved until the 1.0 release.
• Map the diff
• Use --stat, --dirstat, and --name-status outputs to spot hot directories and file types.
• For suspicious files, prefer git diff --word-diff BASE...TARGET -- <path>.
• Note any deleted or newly added tests, config, migrations, or scripts.
• Analyze risk
• Walk through the categories in references/review-checklist.md (breaking changes, regression clues, improvement opportunities).
• When you suspect a risk, cite the specific file/commit and explain the behavioral impact.
• For every finding, include all of: Evidence, Impact, and Action.
• Severity calibration:
• 🟢 LOW: low blast radius or clearly covered behavior; no release gate impact.
• 🟡 MODERATE: plausible user-facing regression signal; needs validation but not a confirmed blocker.
• 🔴 HIGH: confirmed or strongly evidenced release-blocking issue.
• Suggest minimal, high-signal validation commands (targeted tests or linters) instead of generic reruns when time is tight.
• Breaking changes do not automatically require a BLOCKED release call when they are already covered by an appropriate version bump and migration/upgrade notes; only block when the bump is missing/mismatched (e.g., patch bump) or when the breaking change introduces unresolved risk.
• Form a recommendation
• State BASE_TAG and TARGET explicitly.
• Provide a concise diff summary (key directories/files and counts).
• List: breaking-change candidates, probable regressions/bugs, improvement opportunities, missing release notes/migrations.
• Recommend ship/block and the exact checks needed to unblock if blocking. If a breaking change is properly versioned (minor/major), you may still recommend a GREEN LIGHT TO SHIP while calling out the change. Use emoji and boldface in the release call to make the gate obvious.
• If you cannot provide a concrete unblock checklist item, do not use BLOCKED.

Output format (required)

All output must be in English.

Use the following report structure in every response produced by this skill. Be proactive and decisive: make a clear ship/block call near the top, and assign an explicit risk level (LOW/MODERATE/HIGH) to each finding with a short impact statement. Avoid overly cautious hedging when the risk is low and tests passed. Always use the fixed repository URL in the Diff section (https://github.com/openai/openai-agents-js/compare/...). Do not use ${GITHUB_REPOSITORY} or any other template variable. Format risk levels as bold emoji labels: 🟢 LOW, 🟡 MODERATE, 🔴 HIGH. Do not use Markdown links in the report. Keep the Diff URL as plain text, and cite repository files as plain text paths with optional line numbers.

Every risk finding must contain an actionable next step. If the report uses **🔴 BLOCKED**, include an Unblock checklist section with at least one concrete command/task and a pass condition.

### Release readiness review (<tag> -> TARGET <ref>)

This is a release readiness report done by `$final-release-review` skill.

### Diff

https://github.com/openai/openai-agents-js/compare/<tag>...<target-commit>

### Release call:
- **<🟢 GREEN LIGHT TO SHIP | 🔴 BLOCKED>** <one-line rationale>

### Scope summary:
- <N files changed (+A/-D); key areas touched: ...>

### Risk assessment (ordered by impact):
1) **<Finding title>**
   - Risk: **<🟢 LOW | 🟡 MODERATE | 🔴 HIGH>**. <Impact statement in one sentence.>
   - Evidence: <specific diff/test/commit signal; avoid generic statements>
   - Files: <path(s)>
   - Action: <concrete next step command/task with pass criteria>
2) ...

### Unblock checklist (required when Release call is BLOCKED):
1. [ ] <concrete check/fix>
   - Exit criteria: <what must be true to unblock>
2. ...

### Notes:
- <working tree status, tag/target assumptions, or re-run guidance>

If no risks are found, include a “No material risks identified” line under Risk assessment and still provide a ship call. If you did not run local verification, do not add a verification status section or use it as a release blocker; note any assumptions briefly in Notes. If the report is not blocked, omit the Unblock checklist section.

Resources

• scripts/find_latest_release_tag.sh: Fetches remote tags and returns the newest tag matching a pattern (default v*).
• references/review-checklist.md: Detailed signals and commands for spotting breaking changes, regressions, and release polish gaps.

Release Diff Review Checklist

Quick commands

• Sync tags: git fetch origin --tags --prune.
• Identify latest release tag (default pattern v*): git tag -l 'v*' --sort=-v:refname | head -n1 or use scripts/find_latest_release_tag.sh.
• Generate overview: git diff --stat BASE...TARGET, git diff --dirstat=files,0 BASE...TARGET, git log --oneline --reverse BASE..TARGET.
• Inspect risky files quickly: git diff --name-status BASE...TARGET, git diff --word-diff BASE...TARGET -- <path>.

Gate decision matrix

• Choose 🟢 GREEN LIGHT TO SHIP when no concrete blocking trigger is found.
• Choose 🔴 BLOCKED only when at least one blocking trigger has concrete evidence and a defined unblock action.
• Blocking triggers:
• Confirmed regression/bug introduced in the diff.
• Confirmed breaking public API/protocol/config change with missing or mismatched versioning/migration path.
• Concrete data-loss/corruption/security-impacting issue with unresolved mitigation.
• Release-critical build/package/runtime break introduced by the diff.
• Non-blocking by itself:
• Large refactor or high file count.
• Speculative risk without evidence.
• Not running tests locally.
• If uncertain, keep gate green and provide focused follow-up checks.

Actionability contract

• Every risk finding should include:
• Evidence: specific file/commit/diff/test signal.
• Impact: one-sentence user or runtime effect.
• Action: concrete command/task with pass criteria.
• A BLOCKED report must contain an Unblock checklist with at least one executable item.
• If no executable unblock item exists, do not block; downgrade to green with follow-up checks.

Breaking change signals

• Public API surface: removed/renamed exports, changed parameters/return types, default values changed, new required options, stricter validation.
• Protocol/schema: request/response fields added/removed/renamed, enum changes, JSON shape changes, ID formats, pagination defaults.
• Config/CLI/env: renamed flags, default behavior flips, removed fallbacks, environment variable changes, logging levels tightened.
• Dependencies/platform: major version bumps, Node/TypeScript target changes, polyfill removal, new peer dependencies.
• Persistence/data: migration scripts missing, data model changes, stored file formats, cache keys altered without invalidation.
• Docs/examples drift: examples still reflect old behavior or lack migration note.
• Semver alignment: breaking changes should be paired with the expected version bump and clear migration notes; treat mismatches as blockers, not the breaking change alone. Project policy: routine releases are patch; use minor for breaking changes or major feature additions; reserve major until 1.0.

Regression risk clues

• Large refactors with light test deltas or deleted tests; new skip/todo markers.
• Concurrency/timing: new async flows, retries, timeouts, debounce/caching changes, race-prone patterns.
• Error handling: catch blocks removed, swallowed errors, broader catch-all added without logging, stricter throws without caller updates.
• Stateful components: mutable shared state, global singletons, lifecycle changes (init/teardown), resource cleanup removal.
• Third-party changes: swapped core libraries, feature flags toggled, observability removed or gated.

Improvement opportunities

• Missing coverage for new code paths; add focused tests.
• Performance: obvious N+1 loops, repeated I/O without caching, excessive serialization.
• Developer ergonomics: unclear naming, missing inline docs for exported APIs, missing examples for new features.
• Release hygiene: add migration/upgrade note when behavior changes; ensure changelog/notes capture user-facing shifts.

Evidence to capture in the review output

• BASE tag and TARGET ref used for the diff; confirm tags fetched.
• High-level diff stats and key directories touched.
• Concrete files/commits that indicate breaking changes or risk, with brief rationale.
• Tests or commands suggested to validate suspected risks (include pass criteria).
• Explicit release gate call (ship/block) with conditions to unblock.
• Unblock checklist section when (and only when) gate is BLOCKED.