final-release-review

Final Release Review

Purpose

Audit BASE_TAG...TARGET in one of two modes:

• Pre-release planning: use when the user asks to plan the next release or when the target, normally origin/main, does not yet declare a release candidate. The user may still supply a tentative patch or minor intent. Recommend the compatible type; do not treat unchanged package metadata as a blocker.
• Final candidate: use when the user asks for a final candidate decision, the target is a release branch, or target package metadata has already been bumped beyond BASE for the next release. Compare the candidate intent with the minimum release type required by the diff.

In both modes, find concrete regressions and release risks, independently determine version compatibility, review the latest open documentation PRs before claiming coverage is missing, and produce an actionable release handoff. Keep documentation readiness separate from the release gate. The release call is a controlling checker result: callers must stop on BLOCKED and may continue only on GREEN LIGHT TO SHIP. Producing the report text is not itself a passing result.

Quick start

1. Ensure the repository root is openai-agents-python. When a caller supplies a dedicated candidate worktree, run every local inspection from that worktree rather than another checkout of the repository.
2. Sync remote tags and choose the previous release:

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

3. Refresh and resolve the target, defaulting to origin/main:

   git fetch origin main --prune
   TARGET="$(git rev-parse origin/main)"
   

4. Resolve review mode independently from release intent:
   1. Honor an explicit user request for pre-release planning or final-candidate review.
   2. Otherwise, use final-candidate mode only when the target is a release branch or its package metadata has already been bumped beyond BASE for the next release.
   3. Otherwise, use pre-release planning mode.
5. Resolve release intent separately, without asking when repository state already answers it:
   1. User-supplied version or patch/minor intent.
   2. A target branch name or target package version that declares the next release.
   3. Otherwise, set intent to unspecified.
   4. If final-candidate mode was explicitly requested but intent remains unspecified, ask for the intended type or version before issuing a final-candidate gate. If the user prefers an uninterrupted review, switch to pre-release planning and make a recommendation instead.
6. Snapshot the release diff:

   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}"
   

7. Audit the diff with references/review-checklist.md, determine the minimum release type, and prove or dismiss each candidate against the released contract.
8. Discover and review relevant open documentation PRs using current read-only GitHub state. Do not infer coverage from local branches, titles, or historical context.
9. Report the release intent, ship/block gate, risk assessment, documentation coverage, and conditional minor-release Key Changes draft.