Skill: release-readiness

Purpose

Most developer teams do not cut formal releases — they merge to main and deploy. A pre-release checklist that assumes git tags, a VERSION file, and a CHANGELOG is useless to them. This skill detects which workflow the project actually uses, then runs the right checklist: a lightweight pre-merge gate for continuous deployment teams, or a full release gate for teams that tag and version.

Trigger phrases

• "am I ready to release"
• "pre-release check"
• "release readiness"
• "release-readiness"
• "can I ship this"
• "is this ready to tag"
• "is this ready to merge"
• "pre-release gate"

Steps

1. Detect the workflow mode

Run these in parallel:

# Does the repo use formal versioning?
cat VERSION 2>/dev/null
cat package.json 2>/dev/null | grep '"version"'
cat pyproject.toml 2>/dev/null | grep '^version'
cat Cargo.toml 2>/dev/null | grep '^version'

# Does the repo use git tags?
git describe --tags --abbrev=0 2>/dev/null || echo "(no tags)"
git tag --list | tail -5

# CHANGELOG location
ls CHANGELOG.md CHANGELOG HISTORY.md RELEASES.md 2>/dev/null

Classify the repo into one of two modes:

State the detected mode at the top of the report. If ambiguous, ask: "Does this project cut versioned releases with git tags, or does it deploy continuously from main?"

2. Pre-merge gate (Continuous deployment mode — runs Gates 3, 5, 7, 8 only)

Skip version and CHANGELOG gates entirely. Run only:

• Gate 3 — No debug code in the diff against base branch
• Gate 5 — Migration notes written if migrations are present
• Gate 7 — No uncommitted changes
• Gate 8 — Branch is up to date with base

Report with the header: ## Pre-Merge Readiness — <branch-name> instead of a version number.

3. Full release gate (Formal release mode — runs all 8 gates)

Evaluate each gate below. Mark each PASS, FAIL, or SKIP (with reason).

Ask the user: "What version are you releasing?" if it cannot be determined from the version file.

#### Gate 1 — Version is bumped

• Read the version from the detected version source(s).
• Compare against the most recent git tag.
• PASS: current version is higher than the last tag (semantic version comparison).
• FAIL: version matches the last tag — not bumped.
• SKIP: no version file found (note it as a gap, do not block).

#### Gate 2 — CHANGELOG entry exists for this version

• Read the top of CHANGELOG.md (or equivalent).
• Check whether there is a section header matching the release version (e.g. ## [1.4.0] or ## 1.4.0).
• PASS: matching section found with at least one bullet point.
• FAIL: no section for this version, or section is empty.
• SKIP: no CHANGELOG file exists (note it, recommend write-changelog skill).

#### Gate 3 — No debug code in the diff

Use the last tag as the diff base in formal release mode; use the base branch (main/master) in CD mode.

# Formal release mode
git diff $(git describe --tags --abbrev=0 2>/dev/null)..HEAD -- '*.js' '*.ts' '*.py' '*.go' '*.rb' '*.java' | grep -E "^\+" | grep -iE "console\.log|print\(|debugger|breakpoint\(\)|pdb\.set_trace|binding\.pry|TODO.*release|FIXME.*release|DO NOT MERGE|fmt\.Println"

# CD mode
git diff main..HEAD -- '*.js' '*.ts' '*.py' '*.go' '*.rb' '*.java' | grep -E "^\+" | grep -iE "console\.log|print\(|debugger|breakpoint\(\)|pdb\.set_trace|binding\.pry|DO NOT MERGE|fmt\.Println"

• PASS: no matches.
• FAIL: list each matching file and line. Do not block on console.error or console.warn — those are legitimate.

#### Gate 4 — Feature flags cleaned up

Detect feature flag patterns in the diff since last tag:

git diff $(git describe --tags --abbrev=0 2>/dev/null)..HEAD | grep -iE "feature_flag|featureFlag|isEnabled|launch_darkly|unleash|flipper|FEATURE_" | grep "^\+"

• PASS: no new feature flag references added in this release, or all flags added in this diff are documented in the CHANGELOG as intentional.
• WARN (non-blocking): new flag references found — list them and ask "Are these intentional? If so, confirm they are documented."
• This gate never produces a hard FAIL — flag debt is common; the goal is awareness.

#### Gate 5 — Migration notes written (if applicable)

Check whether the diff includes database migrations, API breaking changes, or config changes:

# Formal release mode (diff from last tag)
git diff $(git describe --tags --abbrev=0 2>/dev/null)..HEAD --name-only | grep -iE "migration|migrate|schema|alembic|flyway|liquibase"
git log $(git describe --tags --abbrev=0 2>/dev/null)..HEAD --pretty=format:"%s %b" | grep -i "BREAKING CHANGE"

# CD mode (diff from base branch)
git diff main..HEAD --name-only | grep -iE "migration|migrate|schema|alembic|flyway|liquibase"
git log main..HEAD --pretty=format:"%s %b" | grep -i "BREAKING CHANGE"

• PASS: no migrations or breaking changes detected.
• PASS: migrations detected AND a migration/upgrade guide exists in docs/, CHANGELOG.md, or a MIGRATION.md file.
• FAIL: migrations or breaking changes detected but no migration notes found anywhere.

#### Gate 6 — Deployment documentation is current

Check for a deployment or operations doc:

ls docs/deployment* docs/deploy* docs/ops* DEPLOY.md OPERATIONS.md runbook* 2>/dev/null

• If a deployment doc exists: check whether it was modified in this release cycle (since last tag). If the diff includes infra/config/env changes but the deployment doc was NOT touched, flag it.
• PASS: no deployment-impacting changes, or deployment doc was updated.
• WARN (non-blocking): deployment-impacting changes detected (new env vars, Docker changes, config keys) but deployment doc unchanged.
• SKIP: no deployment doc exists — note it as a gap, do not block.

#### Gate 7 — No uncommitted changes

git status --short

• PASS: working tree is clean.
• FAIL: uncommitted or unstaged changes exist. A release should be cut from a clean working tree.

#### Gate 8 — Branch is up to date with base

git fetch origin --dry-run 2>&1
git rev-list HEAD..origin/main --count 2>/dev/null   # replace 'main' with detected base branch

• PASS: branch is at or ahead of the remote base — nothing to pull.
• FAIL: remote has commits the local branch does not — rebase or merge before releasing.

4. Produce the readiness report

Output in this format:

## Release Readiness — v<VERSION>
<!-- or: ## Pre-Merge Readiness — <branch-name> (CD mode) -->

| Gate | Status | Notes |
|------|--------|-------|
| 1. Version bumped | ✅ PASS | v1.4.0 > v1.3.2 (last tag) |
| 2. CHANGELOG entry | ❌ FAIL | No ## [1.4.0] section found |
| 3. No debug code | ✅ PASS | |
| 4. Feature flags | ⚠️ WARN | 2 new flags added — confirm intentional |
| 5. Migration notes | ✅ PASS | No migrations detected |
| 6. Deployment docs | ⚠️ WARN | New env var STRIPE_KEY detected; DEPLOY.md unchanged |
| 7. Clean working tree | ✅ PASS | |
| 8. Branch up to date | ✅ PASS | |

### Verdict: BLOCK — 1 failure must be resolved before releasing.

### Required actions

**Gate 2 — CHANGELOG entry missing**
Run the `write-changelog` skill to generate the entry, or add a `## [1.4.0] — YYYY-MM-DD` section manually.

### Advisory (non-blocking)

**Gate 4 — Feature flags**
New flags in this diff: `FEATURE_NEW_CHECKOUT`, `featureFlagBetaDashboard`
Confirm these are intentional and document them in the CHANGELOG if user-facing.

**Gate 6 — Deployment docs**
`STRIPE_KEY` added to `.env.example` but not mentioned in `DEPLOY.md`.
Consider adding a note so operators know to provision this before deploying.

Verdict rules:

• Any gate marked FAIL → overall verdict is BLOCK
• Gates marked WARN are advisory — list them but do not block
• Gates marked SKIP are gaps — list them as recommendations, do not block
• All gates PASS or WARN/SKIP only → verdict is READY TO RELEASE (formal mode) or READY TO MERGE (CD mode)

5. Offer next steps

After the report, offer:

"Would you like me to run write-changelog to fix Gate 2, or address another failing gate first?"

Do not cut the tag, push, or deploy automatically.

Output

• A gate-by-gate status table
• A single BLOCK or READY TO RELEASE verdict
• Specific remediation steps for each FAIL
• Advisory notes for each WARN

Notes

• This skill reads and reports. It does not write files, commit, tag, or deploy unless the user explicitly asks and triggers the relevant skill (write-changelog, pr-summary).
• The checklist is intentionally language-agnostic. Gates adapt to what is found — missing artefacts are SKIP, not FAIL, unless they directly prevent a safe release.
• For monorepos: ask the user "Which package or service are we releasing?" and scope all checks to that subdirectory.
• Why dual-mode matters: ~60% of developer teams use continuous deployment from main with no formal versioning (GitHub Octoverse, DORA 2024). A skill that assumes git tags and a CHANGELOG fails silently for the majority. CD mode runs the gates that matter for every team (no debug code, migration notes, clean tree, up-to-date branch) without demanding artefacts that most projects don't have.
• Pairs with: write-changelog (Gate 2 remediation in formal mode), commit-history-audit (run before this skill), pr-summary (after READY verdict, to create the PR).