---
name: scorpio-release
description: Prepare code for release — generate PR descriptions, compile release notes, run pre-merge checklists, and define post-merge verification. Use after scorpio-qa-rework approves all tasks and the feature branch is ready to ship.
---

# Release Plan Prep

A structured methodology for preparing approved code for release. This skill bridges the gap between "QA approved on a feature branch" and "merged and shipped." It produces all the artifacts needed for a clean, well-documented release — but always requires user approval before any action.

## Prerequisites

Before preparing a release, you need:
- All tasks on the branch approved by **scorpio-qa-rework** (no outstanding rework)
- Clean feature branch with all commits
- QA reports available for reference

## Release Prep Phases

```
Phase 1: Audit      → Verify branch is release-ready
Phase 2: Compile    → Gather all changes, tasks, and QA results
Phase 3: Generate   → Produce PR description, release notes, checklists
Phase 4: Present    → Deliver artifacts for user review and approval
```

## Phase 1: Audit

Verify the branch is in a releasable state.

### Release Readiness Checklist

You MAY run read-only git commands to audit release readiness (for example: `git status`, `git branch --show-current`, `git log`, `git diff --stat`). Do NOT run mutating git commands (`git commit`, `git checkout`, `git rebase`, `git merge`, `git push`).

Run quality gates only — through the config-resolved runner (see [docs/GATES.md](../../docs/GATES.md)):
```bash
node scripts/gate.mjs required   # the definition-of-done set (lint/typecheck/unit/build per config)
# or run individually: node scripts/gate.mjs check | unit | build | e2e
```

### Audit Report

```markdown
## Release Audit

**Branch**: [branch-name]
**Base**: [git.baseBranch]
**Commits**: [N] commits ahead of [git.baseBranch]
**Uncommitted changes**: None | [list]

### Quality Gates
| Gate | Result |
|------|--------|
| Lint | PASS / FAIL |
| Type Check | PASS / FAIL |
| Tests | PASS / FAIL ([N] passed, [N] failed) |
| Build | PASS / FAIL |

### Task Status
| Task | QA Status | Rework | Final Status |
|------|-----------|--------|-------------|
| [TASK-001] | PASS | None | Approved |
| [TASK-002] | PASS | 1 cycle | Approved |

### Blockers
- [ ] None | [List any blockers preventing release]
```

If any quality gate fails or tasks are unapproved, **stop and report**. Do not proceed to Phase 2.

## Phase 2: Compile

Gather all information needed for release artifacts.

### Information Sources

| Source | What to Extract |
|--------|----------------|
| Git log | All commits on the branch, authors, messages |
| Task files | Task IDs, titles, descriptions, acceptance criteria |
| QA reports | Test results, findings, approval status |
| Rework history | What was fixed during QA cycles |

### Compile Changes

Use read-only git commands to compile the change list when available (for example `git log --oneline`, `git diff --name-status`, `git diff --stat`). If git access is limited, fall back to task completion reports and QA reports.

### Organize by Category

Group changes using conventional commit types:

```markdown
## Changes

### Features
- [feat commits and their task references]

### Bug Fixes
- [fix commits and their task references]

### Chores
- [chore commits]

### Tests
- [test commits]

### Files Changed
- [N] files modified
- [N] files added
- [N] files deleted
```

## Phase 3: Generate

Produce release artifacts.

### Artifact 1: PR Description

```markdown
## Summary
[2-3 sentences describing what this PR delivers. Focus on user-facing value.]

## Changes

### Features
- [Feature 1]: [brief description] ([TASK-ID])
- [Feature 2]: [brief description] ([TASK-ID])

### Bug Fixes
- [Fix 1]: [brief description] ([TASK-ID])

### Other
- [Chore/refactor descriptions if any]

## Tasks Completed
| Task | Title | QA Status |
|------|-------|-----------|
| [TASK-001] | [Title] | Approved |
| [TASK-002] | [Title] | Approved |

## QA Summary
- All tasks reviewed by scorpio-qa-final
- [N] QA cycles completed
- [N] findings resolved
- [N] findings deferred (see Deferred Items below)

## Deferred Items
- [Any Medium/Low findings from QA that were classified as Defer]

## Test Plan
- [ ] All automated tests pass (lint, typecheck, unit, integration)
- [ ] [Manual verification step 1]
- [ ] [Manual verification step 2]

## Screenshots
[If UI changes, include before/after screenshots or references to QA report screenshots]
```

### Artifact 2: Release Notes

For user-facing changelogs:

```markdown
## [Version or Feature Name] — [Date]

### New
- [User-facing feature description]
- [User-facing feature description]

### Fixed
- [User-facing bug fix description]

### Improved
- [User-facing improvement description]
```

**Rules for release notes:**
- Write from the user's perspective, not the developer's
- No technical jargon (no "refactored the service layer")
- Focus on what changed for the user
- Skip internal chores and test-only changes

### Artifact 3: Pre-Merge Checklist

```markdown
## Pre-Merge Checklist

### Code Quality
- [ ] All quality gates pass (lint, typecheck, tests, build)
- [ ] No TODO/FIXME/HACK left in changed code
- [ ] No debug logging or console statements
- [ ] No hardcoded secrets or credentials

### QA
- [ ] All tasks approved by scorpio-qa-rework
- [ ] All Critical and High findings resolved
- [ ] Deferred items documented and acceptable

### Branch Health
- [ ] Branch is up to date with [git.baseBranch] (rebased or merged)
- [ ] No merge conflicts
- [ ] Commit history is clean and follows conventions

### Documentation
- [ ] README updated (if applicable)
- [ ] API documentation updated (if new/changed endpoints)
- [ ] Release notes drafted

### Deployment
- [ ] Environment variables added/updated (if applicable)
- [ ] Database migrations ready (if applicable)
- [ ] Feature flags configured (if applicable)
- [ ] Rollback plan identified
```

### Artifact 4: Post-Merge Verification

```markdown
## Post-Merge Verification

After merging to [git.baseBranch], verify:

### Immediate (within minutes)
- [ ] CI/CD pipeline passes on [git.baseBranch]
- [ ] Build/deploy succeeds
- [ ] Application starts without errors

### Smoke Test (within the hour)
- [ ] [Core feature 1] works as expected
- [ ] [Core feature 2] works as expected
- [ ] No new errors in logs/monitoring

### Acceptance (within the day)
- [ ] [Acceptance criterion 1 from tasks]
- [ ] [Acceptance criterion 2 from tasks]
- [ ] No user-reported issues

### Rollback Trigger
If any of the following occur, initiate rollback:
- Application fails to start
- Critical user-facing feature is broken
- Error rate exceeds [threshold]
- Data integrity issue detected
```

## Phase 4: Present

Deliver all artifacts to the user for review.

### Presentation Format

```markdown
# Release Prep: [Branch Name]

## Audit: READY / NOT READY
[Link to audit details]

## PR Description
[Full PR description — ready to paste]

## Release Notes
[Full release notes — ready to paste]

## Pre-Merge Checklist
[Checklist with current status]

## Post-Merge Verification
[Verification steps]

---

## Next Steps

When you're ready:
1. Review the PR description and release notes above
2. Complete any unchecked items on the pre-merge checklist
3. Create the PR using: `gh pr create --title "[title]" --body "[body]"`
4. After merge, follow the post-merge verification steps

**Note**: This skill does NOT create the PR. You control when and how it's created.
```

### User Approval Gate

**This skill produces artifacts only.** It never:
- Creates PRs
- Merges branches
- Pushes code
- Modifies the repository

The user takes all release actions manually, using the prepared artifacts as input.

## Handling Edge Cases

### Multiple Feature Branches

If a release includes work from multiple branches:
1. Prep each branch separately
2. Note dependencies between branches
3. Suggest merge order

### Hotfix Releases

For urgent fixes:
1. Skip the full release notes format
2. Use a minimal PR description focused on the fix
3. Emphasize rollback plan in post-merge verification

### First Release / No Existing Process

If the project has no release process yet, suggest a minimal one:
```markdown
## Suggested Release Process
1. PR to [git.baseBranch] with description (from scorpio-release)
2. One reviewer approves
3. Merge (squash or merge commit — your preference)
4. Verify deployment
```

## What NOT To Do

- Do not run mutating git commands (commit/checkout/rebase/merge/push) as part of release prep
- Do not create PRs, merge branches, or push code
- If a user asks for push/merge while using this skill, stop scorpio-release output and hand off to a separate git-ops step
- Do not proceed if quality gates fail
- Do not proceed if tasks have unapproved QA
- Do not write release notes with developer jargon
- Do not skip the pre-merge checklist
- Do not assume deployment process — ask if unclear
- Do not include deferred QA findings as blockers

## Skill Chain

This skill completes the development pipeline:

```
[planning] → scorpio-execute → scorpio-qa-final → scorpio-qa-rework → scorpio-release → [user ships]
```

### Full Pipeline
```
Planning:  scorpio-project-intake | scorpio-feature-intake | scorpio-bug-intake
Design:    scorpio-project-artifacts + scorpio-task-plan | scorpio-feature-plan | scorpio-bug-investigate
Build:     scorpio-execute
Validate:  scorpio-qa-final → scorpio-qa-rework → (rework loop)
Release:   scorpio-release → user creates PR → user merges → post-merge verification
```