release-manager

What this skill does

# Release Manager

The agent automates release management by parsing conventional commits into structured changelogs, determining semantic version bumps, and assessing release readiness with checklists, rollback runbooks, and stakeholder communication plans.

## Quick Start

```bash
# Generate changelog from conventional commits
git log --oneline v1.0.0..HEAD | python changelog_generator.py --version 1.1.0 --format both

# Determine version bump from commit history
git log --oneline v1.0.0..HEAD | python version_bumper.py --current-version 1.0.0 --analysis

# Assess release readiness
python release_planner.py --input release-plan.json --include-checklist --include-rollback
```

---

## Core Workflows

### Workflow 1: Generate Changelog and Version Bump

1. Collect commits since last tag: `git log --oneline v1.0.0..HEAD`
2. Pipe to `changelog_generator.py` to produce a Keep-a-Changelog-format CHANGELOG
3. Pipe to `version_bumper.py` to determine MAJOR/MINOR/PATCH bump from commit types
4. Review changelog grouping (Added, Fixed, Changed, Breaking Changes)
5. **Validation checkpoint:** All `feat` commits appear under Added; all `fix` under Fixed; breaking changes highlighted

```bash
git log --oneline v1.2.0..HEAD | python changelog_generator.py \
  --version 1.3.0 --date 2026-03-21 --base-url https://github.com/org/repo --summary
```

### Workflow 2: Assess Release Readiness

1. Prepare release plan JSON with features, quality gates, stakeholders, and target date
2. Run `release_planner.py` with checklist, communication, and rollback flags
3. Review blocking issues and readiness score
4. Address blockers (missing approvals, failed gates, overdue items)
5. **Validation checkpoint:** Readiness score >80%; zero blocking issues; rollback runbook generated with time estimates

```bash
python release_planner.py --input release-plan.json \
  --output-format json --include-checklist --include-communication --include-rollback
```

### Workflow 3: Hotfix Release

1. Create hotfix branch from last stable tag
2. Apply minimal fix and run `version_bumper.py` with `--prerelease rc`
3. Generate changelog entry for the fix
4. Assess readiness with expedited checklist
5. **Validation checkpoint:** Fix addresses root cause only; rollback procedure tested; stakeholders notified

---

## Version Bump Rules

| Commit Type | Bump | Example |
|-------------|------|---------|
| `BREAKING CHANGE` or `!` suffix | MAJOR | `feat!: remove deprecated API` |
| `feat` | MINOR | `feat(auth): add OAuth2` |
| `fix`, `perf`, `security` | PATCH | `fix(api): resolve race condition` |
| `docs`, `test`, `chore`, `ci` | None | `docs: update README` |

Pre-release progression: `alpha.N` -> `beta.1` -> `rc.1` -> stable release.

---

## Rollback Triggers

- **Error rate:** >2x baseline within 30 minutes
- **Latency:** >50% P95 increase
- **Feature failures:** Core functionality broken
- **Security incident:** Vulnerability exploited
- **Data corruption:** Database integrity compromised

---

## Anti-Patterns

- **Monolithic releases** -- large, infrequent releases with high blast radius; prefer small, frequent releases
- **Manual deployments** -- error-prone and inconsistent; automate every step that can be automated
- **No rollback plan** -- every release must have a tested rollback procedure before going live
- **Skipping quality gates** -- deploying without test coverage, security scan, or dependency audit
- **Last-minute changes** -- code freeze exists for a reason; changes after freeze need explicit approval
- **Non-conventional commits** -- free-form commit messages break changelog generation and version bumping
- **Environment drift** -- staging must mirror production; drift causes false confidence in testing

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| Changelog generator produces empty output | Non-conventional commit messages that don't match the `type(scope): description` pattern | Ensure all commits follow conventional commit format; non-matching messages default to `chore` type which is excluded from user-facing changelogs |
| Version bumper recommends `none` despite meaningful commits | Commits use types in the ignore list (`test`, `ci`, `build`, `chore`, `docs`, `style`) | Use `feat` for new features and `fix` for bug fixes; override with `--custom-rules` to map additional types to bump levels |
| Release planner reports `blocked` status unexpectedly | Missing required approvals (`pm_approved`, `qa_approved`) on features or failed required quality gates | Review the `blocking_issues` array in the assessment output; ensure all features have the necessary approval flags set to `true` in the input JSON |
| Pre-release version not incrementing correctly | Existing pre-release type does not match the requested `--prerelease` type, causing a reset to `.1` | When promoting from alpha to beta or beta to rc, the counter resets to 1 by design; to stay on the same track, pass the same pre-release type |
| Git log parsing misses commits | Input uses full `git log` format but lines are not properly indented with 4 spaces | Use `git log --oneline` for the simplest input format, or ensure the full format output preserves the standard 4-space commit message indent |
| Readiness score seems too low | Quality gates default to `pending` status when not explicitly set, and pending gates score zero points | Provide explicit `quality_gates` with accurate `status` values in the release plan JSON, or complete the gates before running assessment |
| Rollback time estimate is inaccurate | Default rollback steps use generic time estimates that don't reflect your infrastructure | Supply custom `rollback_steps` in the release plan JSON with `estimated_time` values that match your actual deployment environment |

## Success Criteria

- **Changelog accuracy**: 100% of conventional commits are correctly categorized (feat to Added, fix to Fixed, etc.) with zero miscategorized entries
- **Version bump correctness**: Recommended version matches SemVer rules in all cases -- breaking changes produce MAJOR, features produce MINOR, fixes produce PATCH
- **Readiness assessment coverage**: All blocking issues (missing approvals, failed quality gates, overdue timelines) are surfaced with zero false negatives
- **Release cycle time reduction**: Teams using the planner reduce release preparation time by 40% or more compared to manual checklist tracking
- **Rollback preparedness**: Every release assessed by the planner has a complete, actionable rollback runbook with time estimates and verification steps
- **Stakeholder communication**: Communication plans cover all identified stakeholders with appropriate timing (T-48h external, T-24h internal, T+1h post-deploy)
- **Tool integration time**: New teams can configure and run all three scripts against their repository within 30 minutes of initial setup

## Scope & Limitations

**This skill covers:**
- Parsing conventional commits and generating structured changelogs in Markdown and JSON formats
- Determining semantic version bumps (major/minor/patch) with pre-release support (alpha, beta, rc)
- Assessing release readiness across features, quality gates, approvals, and timelines
- Generating rollback runbooks, communication plans, and release checklists from structured input

**This skill does NOT cover:**
- Actual CI/CD pipeline execution or deployment automation (see `engineering/ci-cd-pipeline-generator`)
- Live monitoring, alerting, or incident response during deployments (see `engineering/monitoring-alerting-setup`)
- Code review processes or pull request management (see `engineering/code-review-automation`)
- Infrastructure provisioning, container orchestration, or environment management (see `engineering/infrastructure-as-code`)

## Integration Points

| Skill | Integration | Data Flow |
|-------|-------------|-----------|
| `engineering/ci-cd-pipeline-generator` | Embed changelog generation and version bumping as pipeline stage