aiagentskills/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.

Quick start

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

   BASE_TAG="$(.codex/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.

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.
  • 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.

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.

### 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.>
   - Files: <path(s)>
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.

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.