# Release Review

> Compare two git tags or commits and analyze all changes for deployment readiness. Produces two separate reports — one for manual QA (no code details) and one for developers (technical details with code where needed).

- Skill: `morphet81/release-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add morphet81/release-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/morphet81/release-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: morphet81 (https://skillmd.com/u/morphet81)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/morphet81/release-review

---


Compare two git tags or commits and produce two deployment readiness reports: a **QA report** for manual testers (user-facing flows, no code details) and a **Developer report** (technical details, file paths, code snippets where relevant). Both reports identify what must be verified before deploying and flag potential overlooked issues.

**Usage:**
- `/release-review v1.2.0 v1.3.0` - Analyze changes between two tags
- `/release-review abc1234 def5678` - Analyze changes between two commits
- `/release-review v1.2.0 HEAD` - Analyze changes from a tag to current HEAD

**Instructions:**

1. **Parse positional arguments:**
   - `$1` = the starting point (exclusive) — typically the last deployed version. Can be a git tag, commit SHA, branch name, or `HEAD`
   - `$2` = the endpoint (inclusive) — typically the version about to be deployed. Can be a git tag, commit SHA, branch name, or `HEAD`
   - If either `$1` or `$2` is missing, display the following message and **STOP**:
     ```
     ## Missing Arguments

     Usage: /release-review <base-ref> <target-ref>

     Examples:
       /release-review v1.2.0 v1.3.0
       /release-review abc1234 def5678
       /release-review v1.2.0 HEAD
     ```

2. **Validate the references:**
   - Run `git rev-parse --verify <base-ref>` and `git rev-parse --verify <target-ref>` to confirm both references exist
   - If either reference is invalid, display the error and **STOP**:
     ```
     Invalid git reference: "<ref>"
     Make sure the tag, commit, or branch exists locally. You may need to run `git fetch --tags` first.
     ```

3. **Gather all changes:**

   Run the following git commands to build a complete picture of changes between the two references:

   **a) Commit log:**
   - Run `git log --oneline --no-merges <base-ref>..<target-ref>` to list all non-merge commits
   - Run `git log --oneline --merges <base-ref>..<target-ref>` to list merge commits separately (these indicate PR merges and feature boundaries)

   **b) File-level summary:**
   - Run `git diff --stat <base-ref>..<target-ref>` to get the overall change statistics
   - Run `git diff --name-status <base-ref>..<target-ref>` to categorize files as Added (A), Modified (M), Deleted (D), or Renamed (R)

   **c) Full diff for analysis:**
   - Run `git diff <base-ref>..<target-ref>` to get the full diff
   - If the diff is very large, prioritize reading the most impactful files (new files, heavily modified files, config changes, migration files) and skim the rest

4. **Inventory the changes:**

   Organize all changes into a structured inventory, grouped by area of the application:

   ```
   ## Change Inventory: <base-ref> → <target-ref>

   **Commits:** <N> (non-merge) + <N> (merges)
   **Files changed:** <N> added, <N> modified, <N> deleted, <N> renamed

   ### By Area

   #### <Area 1> (e.g., Authentication, API, UI/Components, Database, etc.)
   - `path/to/file.ts` — <brief description of change>
   - `path/to/other.ts` — <brief description of change>

   #### <Area 2>
   - ...

   ### Notable Changes
   - <Highlight any particularly significant or risky changes>
   - <New dependencies added or removed>
   - <Database migrations>
   - <Configuration changes (env vars, feature flags, etc.)>
   - <API contract changes (new endpoints, modified request/response shapes, breaking changes)>
   ```

   **Grouping guidelines:**
   - Group by functional area of the application, not by directory
   - Identify cross-cutting changes that affect multiple areas
   - Call out infrastructure changes separately (CI/CD, build config, deployment scripts)
   - Flag any changes to shared utilities, types, or core modules that could have ripple effects

5. **Analyze deployment risks and testing requirements:**

   For each area of change, assess the risk and identify what must be verified before deployment:

   ```
   ## Deployment Readiness Analysis

   ### Critical — Must verify before deploying
   These changes carry the highest risk and must be manually or automatically verified.

   **#1** — <Area/feature>
   - **What changed:** <concise description>
   - **Risk:** <why this is critical — data loss, auth bypass, breaking API, etc.>
   - **Verify:** <specific things to test — exact user flows, API calls, edge cases>

   **#2** — ...

   ### Important — Should verify
   These changes are significant but lower risk.

   **#3** — <Area/feature>
   - **What changed:** <concise description>
   - **Risk:** <potential impact>
   - **Verify:** <what to check>

   ### Low Risk — Spot check
   These changes are unlikely to cause issues but deserve a quick look.

   **#4** — <Area/feature>
   - **What changed:** <concise description>
   - **Verify:** <quick check>

   ### No Action Needed
   - <List of changes that don't require verification: docs, comments, formatting, test-only changes, etc.>
   ```

   **Risk assessment criteria:**
   - **Critical:** Auth/security changes, payment/billing, data migrations, breaking API changes, core business logic, shared infrastructure
   - **Important:** New user-facing features, modified existing flows, dependency updates, config changes
   - **Low risk:** UI tweaks, copy changes, logging improvements, non-critical bug fixes
   - **No action:** Documentation, test-only changes, code comments, formatting

6. **Check e2e test coverage:**

   Verify whether the areas identified in step 5 are covered by existing e2e tests.

   **a) Discover the e2e test setup:**
   - Look for Playwright config (`playwright.config.ts`, `playwright.config.js`), Cypress config (`cypress.config.ts`, `cypress.json`), or other e2e frameworks
   - Identify the e2e test directory structure and file patterns
   - If no e2e test framework is found, note this and skip to step 7

   **b) Map changes to e2e coverage:**
   - For each Critical and Important item from step 5, search existing e2e test files for tests that exercise the affected functionality
   - Look for test descriptions, route navigations, selector interactions, and API calls that match the changed areas
   - Read relevant e2e test files to confirm they actually cover the scenarios that need verification

   **c) Report coverage:**

   ```
   ## E2E Test Coverage

   ### Covered
   - **#1** (<Area>) — Covered by `e2e/tests/auth.spec.ts` (tests: "should login with valid credentials", "should reject expired tokens")
   - **#3** (<Area>) — Covered by `e2e/tests/settings.spec.ts` (tests: "should update profile name")

   ### Partially Covered
   - **#2** (<Area>) — `e2e/tests/checkout.spec.ts` covers the happy path but does NOT test the new discount logic added in this release

   ### Not Covered
   - **#5** (<Area>) — No e2e tests found for this flow
   - **#6** (<Area>) — E2e tests exist but are outdated (test references removed component)

   ### Coverage Summary
   - Critical items covered: <N>/<total>
   - Important items covered: <N>/<total>
   - Recommendation: <brief recommendation on whether e2e coverage is sufficient for a safe deployment>
   ```

7. **Flag potential overlooked issues:**

   Look for patterns and risks that might not be obvious from the change inventory alone:

   ```
   ## Potential Overlooked Issues

   ### Dependency & Compatibility
   - <New/updated dependencies that might introduce breaking changes or vulnerabilities>
   - <Peer dependency conflicts>
   - <Node/runtime version requirements that changed>

   ### Data & State
   - <Database migrations that need to be run — and in what order>
   - <Cache invalidation needed after deployment>
   - <State schema changes that could break existing user sessions or stored data>
   - <Background jobs or queues that need to be drained or restarted>

   ### Configuration & Environment
   - <New environment variables that must be set before deployment>
   - <Feature flags that need to be toggled>
   - <Third-party service configuration changes>

   ### Cross-cutting Concerns
   - <Changes to shared utilities/types that affect code outside the diff>
   - <API contract changes that may break mobile or external consumers>
   - <Timing or race condition risks from concurrent changes>
   - <Rollback considerations — can this release be safely rolled back?>

   ### Subtle Risks
   - <Removed error handling or fallback behavior>
   - <Changed default values that could affect existing users>
   - <Renamed or removed public API methods that external code may depend on>
   - <Performance implications of the changes (new queries, larger payloads, etc.)>
   ```

   Only include sections that are relevant — don't pad the report with speculative concerns. Each item should be grounded in something observed in the diff.

8. **Present the final reports:**

   Output two clearly separated reports. Start with a shared changelog, then present the QA report, then the developer report.

   ---

   **8a. Shared Changelog**

   A human-readable summary of everything that changed, suitable for release notes. Use plain language — no file paths or code. Group changes by feature area and write each entry as a user-facing bullet point.

   ```
   ## Changelog: <base-ref> → <target-ref>

   ### New Features
   - <Feature or improvement visible to users — written in plain English>
   - ...

   ### Bug Fixes
   - <Bug that was fixed, described in user-facing terms>
   - ...

   ### Internal & Infrastructure
   - <Non-user-facing changes: config, tooling, dependencies, refactors — keep brief>
   - ...
   ```

   Only include sections that have entries. Omit sections that are empty.

   ---

   **8b. QA Report — Manual Testing**

   For testers performing manual QA. No file paths, no code snippets, no technical internals. Focus entirely on what a tester needs to know and verify.

   ```
   ## QA Report: <base-ref> → <target-ref>

   ### What Changed (QA Summary)
   Describe each changed area in user-facing terms: what the feature does, who it affects, and how users interact with it.

   #### <Area 1> — <Risk level: Critical / Important / Low>
   <1–3 sentence plain-English description of what changed from a user's perspective>

   #### <Area 2> — <Risk level>
   ...

   ### Test Scenarios

   #### Critical — Must verify before deploying
   **<Area/Feature>**
   - [ ] <User-facing test step — e.g., "Log in with a valid account and confirm the dashboard loads">
   - [ ] <Another step>

   #### Important — Should verify
   **<Area/Feature>**
   - [ ] <Test step>

   #### Low Risk — Spot check
   **<Area/Feature>**
   - [ ] <Quick check>

   ### Pre-deployment Checklist (QA)
   - [ ] <QA action — e.g., "Smoke test the login flow on staging">
   - [ ] <QA action — e.g., "Verify checkout works end-to-end with a test card">

   ### Verdict
   **Deployment risk level:** Critical / High / Medium / Low
   **E2E coverage:** Sufficient / Needs attention / Insufficient
   **Recommendation:** <one-sentence summary — e.g., "Safe to deploy after verifying items #1 and #2">
   ```

   ---

   **8c. Developer Report — Technical Details**

   For developers and DevOps. Include file paths, technical context, and code snippets where they help clarify a risk or action. This report contains everything from steps 4–7.

   ```
   ## Developer Report: <base-ref> → <target-ref>

   <Change Inventory from step 4>

   <Deployment Readiness Analysis from step 5>

   <E2E Test Coverage from step 6>

   <Potential Overlooked Issues from step 7>

   ### Pre-deployment Checklist (Technical)
   - [ ] <Technical action — e.g., "Run migration `20240101_add_user_roles.sql`">
   - [ ] <Technical action — e.g., "Set `FEATURE_FLAG_X=true` in production env">
   - [ ] <Technical action — e.g., "Notify mobile team of breaking change to `/api/v2/users` response shape">

   ### Verdict
   **Deployment risk level:** Critical / High / Medium / Low
   **E2E coverage:** Sufficient / Needs attention / Insufficient
   **Recommendation:** <one-sentence summary>
   ```

9. **Handle edge cases:**
   - If there are no changes between the two references, display "No changes found between <base-ref> and <target-ref>." and STOP
   - If the diff is extremely large (hundreds of files), focus on the most impactful changes and note that a full review was not feasible in a single pass
   - If no e2e framework is detected, note it in the coverage section and recommend setting one up
   - If the base ref is ahead of the target ref (reverse order), warn the developer and ask if they meant to swap the arguments