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:

1. "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.)

2. "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):

1. Makefile with test target → make test
2. package.json with test script → npm test
3. go.mod present → go test ./...
4. Cargo.toml → cargo test
5. pyproject.toml or setup.py → pytest or python -m pytest
6. 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):

1. Makefile with build target → make build
2. package.json with build script → npm run build
3. go.mod present → go build ./...
4. Cargo.toml → cargo build --release
5. pyproject.toml with build config → detect build tool (python -m build, poetry build, etc.)
6. 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 requ