review-release

What this skill does

# 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`](../release/SKILL.md), 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 req