Release Review - Pre-Release Readiness Check

Pre-flight checklist before cutting a release. Spawns a scanner agent for static analysis, runs execution-based checks (tests, build, doc freshness), then presents consolidated findings for human review. Runs all checks without interruption, then presents the full picture for decision-making.

Pairing with /release: This skill is the advisory side of the release seam. The mutator side is /release, which invokes /review-release as preflight before doing anything irreversible. If the intent is to cut the release, invoke /release directly — it runs this skill internally. Use /review-release standalone only when auditing readiness without committing to a cut.

Philosophy

Surface issues, don't silently fix them. A release is a commitment to users. Every issue deserves human review before shipping. The only auto-fixes offered are mechanical debug artifact removals.

Run everything, then report. Run all checks — static analysis, tests, build, doc freshness — without interruption. Present the full picture at the end so the user can make informed decisions with complete information.

Err toward reporting. A false positive costs seconds. A missed issue ships to users.

Workflow Overview

┌──────────────────────────────────────────────────────────┐
│                     RELEASE REVIEW                       │
├──────────────────────────────────────────────────────────┤
│  1. Determine release context                            │
│  2. Spawn qa-release-engineer agent (static analysis)    │
│  3. Run test suite                                       │
│  4. Run build verification                               │
│  5. Check documentation freshness                        │
│  6. Present full consolidated report                     │
│  7. User selects which items to address                  │
│  8. Implement selected fixes                             │
│  9. Re-verify affected checks                            │
│ 10. Final summary with release recommendation            │
└──────────────────────────────────────────────────────────┘

Workflow Details

1. Determine Release Context

Detect automatically:

Last tag: git describe --tags --abbrev=0 (if no tags, note this)
Project type and language from manifest files
Test command (detect from Makefile, package.json, go.mod, Cargo.toml, pyproject.toml, etc.)
Build command (detect from Makefile, package.json, go.mod, Cargo.toml, pyproject.toml, etc.)

Ask the user two questions:

"What version are you releasing?" (Optional — enables version consistency checking against a target. If the user skips this, still check that all discovered versions agree with each other.)
"Any checks you want to skip?" Present options:
- Run everything (Recommended)
- Skip build verification (if no build step, or build is very slow)
- Skip doc freshness check
- Skip license compliance

2. Spawn qa-release-engineer Agent

Prompt:

Perform a release readiness scan of this codebase.
Last tag: [tag or "none"]
Target version: [version if provided, else "not specified"]
Scope: entire codebase

Scan for: debug artifacts, version consistency, changelog coverage,
git hygiene, breaking changes, license compliance.

Return structured findings with severity levels (BLOCKER/WARNING/INFO).

3. Run Test Suite

Detect test command (try in order):

Makefile with test target → make test
package.json with test script → npm test
go.mod present → go test ./...
Cargo.toml → cargo test
pyproject.toml or setup.py → pytest or python -m pytest
If none detected, ask the user

Run the test command. Report:

PASS → add as INFO: "Test suite: all tests pass"
FAIL → add as BLOCKER with failure summary (which tests failed, error output)

4. Run Build Verification

Skip if user opted out in step 1.

Detect build command (try in order):

Makefile with build target → make build
package.json with build script → npm run build
go.mod present → go build ./...
Cargo.toml → cargo build --release
pyproject.toml with build config → detect build tool (python -m build, poetry build, etc.)
If none detected, skip with INFO: "No build command detected, skipping build verification"

Run the build command. Report:

PASS → add as INFO: "Build: clean build successful"
FAIL → add as BLOCKER with error output

5. Check Documentation Freshness

Skip if user opted out in step 1.

Spawn doc-maintainer agent in assessment-only mode:

Perform a documentation freshness assessment only. DO NOT make any changes.
Review all documentation files (README, CHANGELOG, CLAUDE.md, doc/, etc.)
for staleness relative to the current codebase.
Report which documents appear outdated and what specifically seems wrong.

Add findings as WARNINGs. Include a note: "Run /tidy-docs to update documentation before release."

6. Present Full Consolidated Report

Merge all findings from steps 2-5 into a single numbered list:

## Release Readiness Report

Target: v1.3.0 (from v1.2.3, 47 commits)

### BLOCKERS (3)
1. [GIT] src/auth.go:42 — Merge conflict markers
2. [DEBUG] src/api/handler.go:15 — console.log("debug request body")
3. [TESTS] 2 test failures: TestPaymentFlow, TestAuthRefresh

### WARNINGS (4)
4. [CHANGELOG] Not updated since v1.2.3
5. [DEBUG] TODO markers in 3 files
6. [LICENSE] New dependency 'foo-lib' — unknown license
7. [DOCS] README.md references removed function parseConfig()

### PASSED
- Version consistency: All manifests agree (1.3.0)
- Build: Clean build successful
- Git hygiene: No large binaries, no tracked secrets
- Breaking changes: No undocumented API changes

Select items to address (e.g., "1-3", "all blockers", "all"):

Use AskUserQuestion with multi-select. Support shortcuts: "all blockers", "all warnings", "all", or specific numbers.

7. Implement Selected Fixes

Group selected items by type and handle appropriately:

Debug artifact removal (auto-fixable)

Handle directly as orchestrator. Remove the debug statement/line. Show the user what was removed.

TODO/FIXME markers (auto-fixable if selected)

Remove the marker comment. Show what was removed. The user selected these knowing they'd be deleted.

Merge conflict markers

Cannot auto-fix — the user must resolve conflicts manually. Report the file and conflicting content. Skip.

Test failures

Cannot auto-fix from here. Suggest: "Test failures require investigation. Fix manually or use /implement to address."

Build failures

Cannot auto-fix from here. Report the error and suggest investigating.

Changelog gaps

Cannot auto-generate meaningful entries. Offer to scaffold a changelog entry by listing commits since last tag, organized by type (features, fixes, etc.). The user fills in the details.

Version mismatches

If the user provided a target version, offer to update version numbers in manifest files to match. This is mechanical and safe for manifests. For source code constants, show the file and line — the user confirms.

License issues

Report only. The user must decide whether the dependency is acceptable.

Doc staleness

Suggest running /tidy-docs. Do not attempt fixes.

Breaking changes

Report only. The user must decide whether to document, revert, or accept.

8. Re-verify Affected Checks

After implementing fixes, re-verify only the checks that were affected:

Debug artifacts removed → quick Grep to confirm none remain
Version numbers updated → re-check consistency
If nothing else changed, skip re-verification

Do NOT re-run the full test suite or build at this step (the user can do that separately). Only re-verify the fast, static checks.

9. Final Summary

## Release Review Complete

### Status
- BLOCKERS resolved: 2/3 (1 requires manual fix)
- WARNINGS addressed: 2/4
- Items skipped: 3 (user declined)

### Changes Made
- Removed 1 console.log statement (src/api/handler.go:15)
- Removed 3 TODO markers

### Remaining Issues
- [BLOCKER] Merge conflict markers in src/auth.go — manual resolution needed
- [WARNING] CHANGELOG.md not updated
- [WARNING] New dependency 'foo-lib' license unverified

### Recommendation
HOLD — 1 unresolved BLOCKER remains

Recommendation logic:

HOLD: Any unresolved BLOCKERs
PROCEED WITH CAUTION: Only WARNINGs remain
READY TO RELEASE: No BLOCKERs or WARNINGs

If changes were made, ask the user if they want to commit:

git add [specific files modified]
git commit -m "$(cat <<'EOF'
chore: pre-release cleanup

[Brief description of what was removed/fixed]
EOF
)"

Agent Coordination

Sequential execution:

One agent at a time
Wait for completion before spawning next

Agents used:

qa-release-engineer: Static analysis scan (step 2)
doc-maintainer: Documentation freshness assessment only (step 5)

State to maintain (as orchestrator):

Release context (last tag, target version, skipped checks)
Agent findings (from qa-release-engineer)
Execution check results (tests, build, docs)
Consolidated finding list with numbering
User selections
Fix results
Running totals for summary

Abort Conditions

Abort workflow:

User interrupts
Not a git repository
No permission to run test/build commands

Do NOT abort for:

No tags found (use initial commit as baseline, note in report)
Individual check failures (report and continue)
Agent finding no issues (exit gracefully — "Release looks clean")
Test or build failures (report as BLOCKERs, continue with other checks)

Test/Build Command Detection

Test commands (try in order):

Makefile with test target → make test
package.json with test script → npm test
go.mod → go test ./...
Cargo.toml → cargo test
pyproject.toml or setup.py → pytest
Ask user if none detected

Build commands (try in order):

Makefile with build target → make build
package.json with build script → npm run build
go.mod → go build ./...
Cargo.toml → cargo build --release
pyproject.toml with build config → python -m build
Skip with INFO if none detected

Example Session

> /review-release

What version are you releasing?
> 2.0.0

Any checks to skip?
> Run everything

Spawning qa-release-engineer agent for static analysis...
Running tests: go test ./...
Running build: make build
Checking documentation freshness...

## Release Readiness Report

Target: v2.0.0 (from v1.9.2, 89 commits)

### BLOCKERS (2)
1. [DEBUG] src/api/handler.go:15 — fmt.Println debug statement
2. [VERSION] Version not bumped to 2.0.0 (currently 1.9.2)

### WARNINGS (4)
3. [CHANGELOG] Not updated since v1.9.2
4. [BREAKING] Removed ParseConfig() — not in changelog
5. [DEBUG] TODO markers in 2 files
6. [DOCS] README.md references removed ParseConfig()

### PASSED
- Tests: All pass
- Build: Clean
- Git hygiene: Clean
- License: Compatible

Select items to address:
> 1, 2, 5

Removing debug statement from src/api/handler.go:15... done.
Updating version to 2.0.0 in package.json... done.
Updating version to 2.0.0 in src/version.go... done.
Removing TODO markers from src/migrate.go:12, src/config.go:55... done.

Re-verifying... no debug artifacts remain, versions consistent.

## Release Review Complete

### Status
- BLOCKERS resolved: 2/2
- WARNINGS addressed: 1/4
- Items skipped: 3 (user declined)

### Changes Made
- Removed 1 debug statement (src/api/handler.go:15)
- Updated version to 2.0.0 in package.json, src/version.go
- Removed 2 TODO markers

### Remaining Issues
- [WARNING] CHANGELOG.md not updated
- [WARNING] Removed ParseConfig() not documented as breaking change
- [WARNING] README.md references removed function (run /tidy-docs)

### Recommendation
PROCEED WITH CAUTION — 3 warnings remain

Commit changes?
> Yes

Committed: "chore: pre-release cleanup for v2.0.0"

review-release

SKILL.mdskills/review-release/SKILL.md