| name | prepare-release |
| description | Release preparation for Stages I-L of the VibeFlow docs-first workflow |
| metadata | {"triggers":["prepare release","deployment","OP-NOTE","close loop","spec reconciliation","Stage I","Stage J","Stage K","Stage L","release checklist"]} |
prepare-release
Release preparation for Stages I-L of the VibeFlow docs-first workflow.
Purpose
This skill guides release preparation through Stages I-L:
- Stage I: Spec Reconciliation (sync docs with implementation)
- Stage J: OP-NOTE Creation (deployment documentation)
- Stage K: Deploy (execute deployment)
- Stage L: Close Loop (update indices, retrospective)
Workflow
Stage I: Spec Reconciliation
│
├── Compare Feature Spec vs actual implementation
├── Update SPEC documents with any deviations
├── Reconcile ADRs with decisions made
└── Ensure docs match deployed reality
│
▼
Stage J: OP-NOTE Creation
│
├── Create docs/op-notes/op-<feature>.md
├── Document: Preflight, Deploy Steps, Monitoring
├── Document: Runbook, Rollback, Post-Deploy Checks
└── Update op-notes/index.md
│
▼
Stage K: Deploy
│
├── Execute preflight checklist
├── Run deployment steps
├── Execute post-deploy verification
└── Monitor for issues
│
▼
Stage L: Close Loop
│
├── Update master indices
├── Mark feature complete
├── Run retrospective (Large track)
└── Archive or link documentation
Usage
Check Release Readiness
/prepare-release check
Validates OP-NOTE completeness and spec reconciliation status.
Create OP-NOTE
/prepare-release opnote <feature-slug>
Creates docs/op-notes/op-<feature-slug>.md from template with all required sections.
Reconcile Specs
/prepare-release reconcile <feature-id>
Compares Feature Spec vs actual implementation and updates divergent docs.
Stage Details
Stage I: Spec Reconciliation
Purpose: Ensure documentation matches implementation before release.
Tasks:
- Compare Feature Spec API Design with actual implementation
- Update any divergent signatures or behaviors
- Review SPEC documents for accuracy
- Update ADRs if decisions changed during implementation
- Document any deviations discovered
Stage J: OP-NOTE Creation
Purpose: Document everything operators need for deployment.
Required Sections:
- Header (file, date, features covered)
- Preflight (prerequisites, migrations, env vars)
- Deploy Steps (ordered commands with verification)
- Monitoring (dashboards, alerts, SLOs)
- Runbook (symptom → diagnose → remediate)
- Rollback (precise steps, data compatibility)
- Post-Deploy Checks (smoke tests, owners)
Location: docs/op-notes/op-<feature-slug>.md
Stage K: Deploy
Purpose: Execute deployment following OP-NOTE.
Pre-Deploy Checklist:
Post-Deploy Checklist:
Stage L: Close Loop
Purpose: Finalize feature lifecycle.
Tasks:
- Update
docs/features/index.md - mark feature complete
- Update
docs/op-notes/index.md - link OP-NOTE
- Update
docs/specs/index.md if new SPECs created
- Create git tag for release
- Run retrospective (Large track only)
Indices to Update:
- Feature index with completion status
- OP-NOTE index with deployment link
- SPEC index with version updates
- ADR index with new decisions
Best Practices
- Never deploy without OP-NOTE: Gate production deployments
- Keep runbooks actionable: Symptom → Diagnose → Remediate
- Test rollback procedures: Don't assume they work
- Update indices promptly: Don't let documentation lag
- Reconcile specs honestly: Document what was actually built
Validation
scripts/validate_opnote.py — Validate OP-NOTE completeness
scripts/reconcile_specs.py — Check spec reconciliation status
References
See assets/:
opnote-template.md — OP-NOTE template
Manifest Update
After completing each stage, update docs/workflow-state.yaml:
Stage I (Reconcile):
Stage J (OP-NOTE):
- Set
stage: J
- Set
docs.opnote: docs/op-notes/op-<slug>.md
Checkpoint #5 (after Stage J):
- Set
checkpoint: 5 after passing validation
- Criteria: OP-NOTE exists with all required sections, spec reconciliation complete
Stage K (Deploy):
Stage L (Close):
Checkpoint #6 (after Stage L):
- Set
checkpoint: 6 after passing validation
- Criteria: Deployment verified, indices updated, git tag created
Git Commit
After completing each stage, ask the user for permission before committing:
Stage I (Reconcile):
git add docs/ docs/workflow-state.yaml
git commit -m "feat(release): reconcile specs with implementation (#ft-<ID>)"
Stage J (OP-NOTE):
git add docs/op-notes/op-<slug>.md docs/workflow-state.yaml
git commit -m "feat(release): create OP-NOTE for <slug> (#ft-<ID>)"
Stage L (Close):
git add docs/workflow-state.yaml
git commit -m "feat(release): close <slug> (#ft-<ID>)"
git tag v<version>-<slug>
gh pr create --title "[ft-<ID>] <Description>" --body "Closes #ft-<ID>"
Replace <slug>, <ID>, <version>, and <Description> with actual values.
Auto-Advance
After each sub-stage commit, directly run /manage-work advance <ID>:
- After Stage I (Reconcile) commit → advances I→J.
- After Stage J (OP-NOTE) commit → advances J→K. The advance command will automatically validate Checkpoint #5 at the J→K boundary.
- After Stage K (Deploy) commit → advances K→L.
- After Stage L (Close) commit → advances L→DONE. The advance command will automatically validate Checkpoint #6 at the L→DONE boundary.