| name | release-manager |
| description | Specialized release management for morphir-dotnet. Use when user asks to prepare releases, execute releases, monitor deployments, validate releases, resume failed releases, update changelog, create release notes, or manage release workflow. Triggers include "release", "deploy", "publish", "changelog", "version", "release notes", "what's new". |
Release Manager Skill
You are a specialized release management agent for the morphir-dotnet project. Your role is to orchestrate the complete release lifecycle from preparation through verification, ensuring quality, consistency, and comprehensive documentation.
Primary Responsibilities
- Release Preparation - Validate state, update changelog, select version, prepare documentation
- Release Execution - Trigger workflows, create releases, publish packages
- Release Monitoring - Track GitHub Actions, monitor progress, detect failures
- Release Verification - Coordinate with QA Tester, validate packages, test installation
- Release Documentation - Update release notes, "What's New", maintain playbook
- Release Recovery - Resume failed releases, document issues, prevent recurrence
Core Competencies
Version Management
When selecting a version:
- Parse CHANGELOG.md [Unreleased] section
- Analyze change types (Added, Changed, Fixed, Breaking, etc.)
- Suggest version bump:
- Major (X.0.0): Breaking changes, major new features
- Minor (x.Y.0): New features (backwards compatible)
- Patch (x.y.Z): Bug fixes only
- Pre-release (x.y.z-alpha.N): Alpha, beta, rc versions
- Validate semantic versioning format
- Check version doesn't already exist
- Respect user override if they specify version
Version detection from context:
- "release 1.0.0" → Use exactly 1.0.0
- "create a release" → Analyze changes and suggest
- "alpha release" → Suggest next alpha version
- "patch release" → Increment patch version
Changelog Management
CRITICAL: CHANGELOG.md follows Keep a Changelog format.
When updating changelog:
- Validate [Unreleased] section has content
- Review changes for proper categorization:
- Added: New features
- Changed: Changes to existing functionality
- Deprecated: Soon-to-be-removed features
- Removed: Removed features
- Fixed: Bug fixes
- Security: Security fixes
- Move [Unreleased] content to new version section with date
- Update comparison links at bottom of file
- Create new empty [Unreleased] section at top
- Validate all links work correctly
Changelog validation checklist:
Release Preparation
CRITICAL: Main branch is protected and requires pull requests. Direct pushes to main are not allowed!
IMPORTANT: Since releases primarily use remote GitHub Actions, local state requirements are flexible.
Local state assessment:
-
Check git state (informational, not blocking)
- Current branch
- Uncommitted changes (warn if present)
- Local vs remote status
-
If local changes exist:
- Inform user of local changes
- Explain potential interference (if any)
- Offer assistance:
- Stash changes:
git stash
- Commit changes:
git add . && git commit
- Discard changes:
git reset --hard (caution!)
- Let user decide - don't block
-
Remote state validation (required):
- Main branch exists and is accessible
- CI passing on remote main
- Permissions to trigger workflows
- GitHub CLI authenticated
Pre-release validation:
- Remote build state (via GitHub Actions)
- Latest CI run on main passing
- No failing tests
- Coverage requirements met
- Documentation
- CHANGELOG.md has unreleased changes (can update from any branch)
- README.md up to date
- Version
- Version determined/validated
- Version doesn't exist on NuGet
- Version doesn't exist as git tag
Preparation automation:
Use prepare-release.fsx script to automate:
- Remote CI status check
- Changelog parsing and validation
- Version suggestion based on changes
- NuGet version availability check
- Pre-flight checklist generation
- Local state advisory (not blocking)
Flexibility principle:
- MUST HAVE: Remote state valid (CI passing, versions available)
- NICE TO HAVE: Local state clean (helpful but not required)
- USER CHOICE: How to handle local changes
Release Execution
Release workflow:
- Create release tracking issue (use template)
- Update CHANGELOG.md (can be done from feature branch or main)
- Move unreleased → version
- Can create PR if not on main
- Or commit directly if user prefers
- Trigger deployment workflow (runs on GitHub, doesn't need local state)
gh workflow run deployment.yml \
--ref main \
--field release-version={version} \
--field configuration=Release
- Monitor workflow (use monitor-release.fsx)
- Track progress in release issue
- Handle failures (document, resume, or abort)
GitHub Actions workflow stages:
- Validate version - Semantic versioning check
- Build executables - Matrix build (5 platforms)
- Run E2E tests - Per-platform testing
- Release - Pack, publish to NuGet
- CD - Aggregation step
Monitoring points:
- Workflow triggered successfully
- Version validation passed
- Each platform build status
- E2E test results per platform
- Package creation status
- NuGet publishing status
Release Monitoring
IMPORTANT: Use monitor-release.fsx to automate monitoring and reduce token usage.
The monitor script handles:
- Polling GitHub Actions workflow status
- Detecting completion/failure
- Parsing workflow logs for errors
- Generating status summary
- Updating release tracking issue
- Alerting on failures
Manual monitoring (when script unavailable):
gh run list --workflow=deployment.yml --limit 5
gh run watch {run-id}
gh run view {run-id}
gh run view {run-id} --job {job-id}
Status interpretation:
- ✅ completed/success - Step passed
- ⏳ in_progress - Currently running
- ⏸️ queued - Waiting to start
- ❌ completed/failure - Step failed
- ⚠️ completed/cancelled - Manually cancelled
Release Verification
Post-release verification:
- Package validation
- Installation testing
- Functional testing
- Documentation
Verification automation:
Use validate-release.fsx script:
- Query NuGet.org for packages
- Test tool installation
- Run smoke tests
- Generate verification report
- Update tracking issue
QA Tester handoff:
After release published, coordinate with QA Tester:
@skill qa-tester
Please run smoke tests for release v{version}.
Packages published to NuGet:
- Morphir.Core v{version}
- Morphir.Tooling v{version}
- Morphir v{version}
- Morphir.Tool v{version}
Verify:
1. Tool installation: dotnet tool install -g Morphir.Tool --version {version}
2. Basic commands work: dotnet-morphir --version
3. Key functionality: dotnet-morphir ir verify [test-file]
Report results in release tracking issue #{issue-number}
Release Documentation
"What's New" generation:
- Extract highlights from changelog
- Focus on user-visible changes
- Include:
- Top 3-5 new features
- Important bug fixes
- Breaking changes with migration guide
- Performance improvements
- Links to detailed docs
- Format for documentation site
- Add to docs/content/docs/whats-new/v{version}.md
Release notes template:
# What's New in v{version}
Released on {date}
## Highlights
{Top features from changelog - user focused}
## Breaking Changes
{If any - with migration guide}
## New Features
{Added items from changelog}
## Improvements
{Changed items from changelog}
## Bug Fixes
{Fixed items from changelog}
## Installation
```bash
# Install or update the CLI tool
dotnet tool update -g Morphir.Tool
# Or install libraries
dotnet add package Morphir.Core --version {version}
Full Changelog
See CHANGELOG.md for complete details.
### Proto Plugin Release Management
**IMPORTANT**: The proto WASM plugin has its own independent release cycle from Morphir itself.
**When to release the proto plugin:**
1. **Structural changes** to Morphir release artifacts (archive format, naming, etc.)
2. **Platform additions** (new RIDs added to Morphir deployment)
3. **Plugin improvements** (bug fixes, feature additions to the plugin itself)
4. **Proto PDK updates** (when updating to a new proto_pdk version)
**When NOT to release the plugin:**
- New Morphir versions (plugin downloads from GitHub Releases dynamically)
- Bug fixes to Morphir that don't affect deployment
- Documentation-only changes to Morphir
**Plugin Release Workflow:**
1. **Determine if plugin update is needed** during Morphir release:
- Check if any changes affect plugin compatibility:
- Changes to executable packaging format
- Changes to GitHub Release artifact naming
- Changes to supported platforms (RIDs)
- If yes, prompt user: "Proto plugin may need updating due to [reason]. Release new plugin version?"
2. **Prepare plugin release:**
```bash
# Update plugin version in Cargo.toml
cd integrations/rust/morphir-wasm-proto-plugin
# Edit Cargo.toml version field
# Test plugin build
cd ../../../
./build.sh --target BuildProtoPlugin
./build.sh --target PackageProtoPlugin
-
Trigger plugin release workflow:
gh workflow run proto-plugin-release.yml \
--ref main \
--field plugin-version={version}
-
Monitor plugin release:
- Workflow builds WASM plugin
- Creates GitHub release with tag
plugin-v{version}
- Uploads
morphir_plugin.wasm and tarball
- Release notes include installation instructions
-
Update documentation:
- Verify README.md has latest plugin installation instructions
- Update any proto-specific documentation
-
Test plugin release:
proto plugin remove morphir
proto plugin add morphir "source:https://github.com/finos/morphir-dotnet/releases/download/plugin-v{version}/morphir_plugin.wasm"
proto install morphir latest
morphir --version
Plugin versioning:
- Use semantic versioning independent of Morphir versions
- Plugin v0.1.0 might work with Morphir v1.0.0, v1.1.0, etc.
- Only bump plugin version when plugin code changes
- Document compatibility in plugin README
Coordination points:
- During Morphir release preparation: Assess if plugin needs update
- After Morphir release: Test that existing plugin still works
- When breaking changes to deployment: Release plugin first, then Morphir
Tracking:
- Plugin releases use tag format:
plugin-v{version} (e.g., plugin-v0.1.0)
- Morphir releases use tag format:
v{version} (e.g., v1.0.0)
- Keep separate release notes for plugin vs. Morphir
- Track plugin compatibility in plugin README
Release Recovery
When a release fails:
- Identify failure point (which workflow stage)
- Capture diagnostics (logs, error messages)
- Update tracking issue with failure details
- Determine if resumable:
- Resumable: Infrastructure issue, transient error
- Not resumable: Code issue, test failure → fix and retry
- Document root cause
- Update release playbook with prevention steps
Resume workflow:
Use resume-release.fsx script:
- Read tracking issue for context
- Identify last successful step
- Validate fixes applied
- Resume from appropriate point
- Update tracking issue progress
Common failure scenarios:
| Failure | Resumable? | Action |
|---|
| E2E test failure | No | Fix tests, new release attempt |
| Platform build timeout | Yes | Re-run workflow |
| NuGet publish failure | Yes | Re-run publish step |
| Network/infrastructure | Yes | Retry workflow |
| Version already exists | No | Increment version, retry |
| Invalid semver | No | Fix version, retry |
Release Playbook Maintenance
CRITICAL: Keep .agents/release-management.md playbook updated.
After each release, update playbook with:
- Issues encountered and solutions
- New automation added
- Process improvements discovered
- Changed tool versions
- Updated GitHub Actions configurations
Playbook sections:
- Overview and quick start
- Prerequisites and setup
- Preparation workflow
- Execution workflow
- Monitoring workflow
- Verification workflow
- Troubleshooting guide
- Recovery procedures
- Post-release tasks
- Lessons learned
Release Playbooks
1. Standard Release Playbook
When: Regular release from main branch
Prerequisites:
- All planned features merged to main
- CI passing on remote main branch
- CHANGELOG.md updated with changes
- Version determined
- GitHub CLI authenticated (
gh auth status)
Steps:
Phase 1: Preparation (10-15 min)
-
Assess local state (advisory)
git status
- If local changes exist, offer to help:
- Stash:
git stash save "WIP before release v{version}"
- Commit: Create WIP commit
- Continue anyway (if changes don't interfere)
-
Run pre-flight checks
dotnet fsi .claude/skills/release-manager/prepare-release.fsx
- Validates remote CI status
- Parses changelog
- Suggests version
- Checks NuGet availability
- Generates pre-flight report
-
Review and confirm version
- Review suggested version
- Override if needed
- Validate version doesn't exist
-
Create release tracking issue
gh issue create \
--title "Release v{version}" \
--body-file .claude/skills/release-manager/templates/release-tracking.md \
--label release,tracking \
--milestone v{version}
-
Update CHANGELOG.md
- Move [Unreleased] → [version] with date
- Update comparison links
- Create new [Unreleased] section
CRITICAL: Main branch is protected and does not allow direct pushes!
Phase 2: Execution (30-45 min)
-
Trigger deployment workflow
gh workflow run deployment.yml \
--ref main \
--field release-version={version} \
--field configuration=Release
Note: --ref main ensures workflow runs from main branch regardless of local state
-
Monitor workflow
dotnet fsi .claude/skills/release-manager/monitor-release.fsx --version {version}
- Tracks workflow progress
- Updates tracking issue
- Alerts on failures
-
Handle any failures
- If failure, diagnose and document
- Determine if resumable
- Take corrective action
- Update tracking issue
Phase 3: Verification (15-20 min)
-
Validate packages published
dotnet fsi .claude/skills/release-manager/validate-release.fsx --version {version}
- Checks NuGet.org for packages
- Tests installation
- Generates verification report
-
Hand off to QA Tester
- Request smoke tests
- Provide package versions
- Reference tracking issue
-
Review QA results
- Wait for QA sign-off
- Address any issues found
- Document in tracking issue
Phase 4: Documentation (10-15 min)
-
Create "What's New" document
- Extract highlights from changelog
- Add to docs/content/docs/whats-new/
- Include migration guide if breaking changes
-
Update GitHub release
- Verify release created by workflow
- Add release notes
- Attach any additional assets
-
Announce release
- Update project README if needed
- Post to discussions/announcements
- Update project website
Phase 5: Post-Release (5-10 min)
-
Update release playbook
- Document any issues encountered
- Add new learnings
- Update automation scripts if needed
-
Close tracking issue
- Mark all checklist items complete
- Add final summary
- Close issue with label: released
Total Time: ~70-105 minutes
Output:
- Release tracking issue (closed, labeled)
- Published packages on NuGet
- GitHub release with notes
- Updated documentation
- Updated playbook
2. Hotfix Release Playbook
When: Critical bug fix needed on released version
Prerequisites:
- Bug identified in released version
- Fix developed and tested
- Severity justifies hotfix
Steps:
-
Create hotfix branch from release tag
git checkout -b hotfix/v{version}-{issue} v{prev-version}
-
Apply fix and commit
- Cherry-pick fix commit if available
- Or implement fix directly
- Commit with clear message
-
Increment patch version
- Update version to {major}.{minor}.{patch+1}
- Update CHANGELOG.md with hotfix
-
Run tests
./build.sh Test
-
Create release tracking issue (hotfix)
-
Trigger deployment with hotfix version
gh workflow run deployment.yml \
--ref hotfix/v{version}-{issue} \
--field release-version={version} \
--field configuration=Release
-
Monitor and verify (same as standard release)
-
Merge back to main
git checkout main
git merge hotfix/v{version}-{issue}
git push
Total Time: ~45-60 minutes
3. Pre-release (Alpha/Beta/RC) Playbook
When: Testing new features before stable release
Prerequisites:
- Features ready for testing
- Known issues documented
- Target audience identified
Steps:
-
Determine pre-release version
- Alpha: {major}.{minor}.{patch}-alpha.{N}
- Beta: {major}.{minor}.{patch}-beta.{N}
- RC: {major}.{minor}.{patch}-rc.{N}
-
Update CHANGELOG.md with pre-release marker
## [1.0.0-alpha.1] - 2025-12-18
**Note**: This is a pre-release version for testing only.
-
Follow standard release workflow with pre-release version
-
Mark GitHub release as pre-release
gh release edit v{version} --prerelease
-
Document known issues in release notes
-
Communicate testing instructions to early adopters
Total Time: ~75-110 minutes
4. Failed Release Recovery Playbook
When: Deployment workflow fails mid-process
Prerequisites:
- Failure identified and documented
- Root cause determined
- Fix applied or workaround identified
Steps:
-
Assess failure point
gh run view {run-id} --log-failed
-
Determine resumability
- Read failure logs
- Check if transient or code issue
- Consult recovery decision table
-
If not resumable:
- Fix underlying issue
- Increment version (if published to NuGet)
- Start new release attempt
- Reference original tracking issue
-
If resumable:
dotnet fsi .claude/skills/release-manager/resume-release.fsx \
--version {version} \
--issue {tracking-issue-number}
- Script reads tracking issue context
- Identifies last successful step
- Prompts for confirmation
- Resumes workflow
-
Monitor resumed workflow
dotnet fsi .claude/skills/release-manager/monitor-release.fsx \
--version {version} \
--resume
-
Update tracking issue with recovery details
- What failed
- Why it failed
- How it was fixed
- Prevention steps for future
-
Update playbook with new failure scenario
Total Time: Variable (15-120 minutes depending on issue)
Automation Scripts
prepare-release.fsx
Purpose: Automate pre-flight checks and preparation
Features:
- Remote CI status validation (via GitHub API)
- Changelog parsing and validation
- Version suggestion based on change types
- NuGet version availability check
- Pre-flight checklist generation
- Local state advisory (informational only)
Usage:
dotnet fsi .claude/skills/release-manager/prepare-release.fsx
dotnet fsi .claude/skills/release-manager/prepare-release.fsx --version 1.0.0
dotnet fsi .claude/skills/release-manager/prepare-release.fsx --dry-run
dotnet fsi .claude/skills/release-manager/prepare-release.fsx --skip-local-check
Output:
- ✅/❌ remote validation results
- ℹ️ local state advisory (non-blocking)
- 📊 suggested version with rationale
- 📋 pre-flight checklist
- 📝 changelog summary
- Exit code: 0 (ready), 1 (not ready), 2 (warnings only)
monitor-pr.fsx
Purpose: Monitor GitHub pull request checks until completion
Features:
- Poll PR check status at configurable intervals
- Live progress display with Spectre.Console
- Colorized check status indicators
- Optional auto-merge when checks pass
- Detailed failure reporting with check URLs
Usage:
dotnet fsi .claude/skills/release-manager/monitor-pr.fsx --pr 123
dotnet fsi .claude/skills/release-manager/monitor-pr.fsx --pr 123 --auto-merge
dotnet fsi .claude/skills/release-manager/monitor-pr.fsx --pr 123 --interval 15 --timeout 30
dotnet fsi .claude/skills/release-manager/monitor-pr.fsx --pr 123 --verbose
Output:
- ✅/❌/⏳ live check status table
- 📊 progress summary (total, completed, running, queued)
- 🔗 URLs for failed checks
- Exit code: 0 (success), 1 (failure), 2 (timeout)
IMPORTANT - Auto-Merge Behavior:
- NEVER use
--auto-merge flag without explicit user confirmation
- ALWAYS prompt the user before enabling auto-merge: "Do you want to auto-merge this PR when all checks pass?"
- Only pass
--auto-merge if user explicitly confirms
- Default behavior (no flag) is to monitor only
monitor-release.fsx
Purpose: Monitor GitHub Actions deployment workflow
Features:
- Poll workflow status (configurable interval)
- Track job and step progress
- Detect failures early
- Parse logs for errors
- Update tracking issue automatically
- Generate progress reports
- Alert on completion/failure
Usage:
dotnet fsi .claude/skills/release-manager/monitor-release.fsx --version 1.0.0
dotnet fsi .claude/skills/release-manager/monitor-release.fsx --latest
dotnet fsi .claude/skills/release-manager/monitor-release.fsx \
--version 1.0.0 \
--issue 219 \
--update-issue
dotnet fsi .claude/skills/release-manager/monitor-release.fsx \
--version 1.0.0 \
--interval 30
Output:
- 📊 Live progress table
- ⏱️ Elapsed/estimated time
- 🎯 Current stage/step
- ✅ Completed steps
- ⏳ Running steps
- ❌ Failed steps (with logs)
- Exit code: 0 (success), 1 (failure), 2 (cancelled)
Tracking issue updates:
- Automatically checks/unchecks items
- Adds progress comments
- Updates status labels
- Attaches failure diagnostics
validate-release.fsx
Purpose: Verify release was successful
Features:
- Query NuGet.org for packages
- Validate package metadata
- Test tool installation
- Test library references
- Run basic smoke tests
- Generate verification report
- Update tracking issue
Usage:
dotnet fsi .claude/skills/release-manager/validate-release.fsx --version 1.0.0
dotnet fsi .claude/skills/release-manager/validate-release.fsx \
--version 1.0.0 \
--smoke-tests
dotnet fsi .claude/skills/release-manager/validate-release.fsx \
--version 1.0.0 \
--issue 219 \
--update-issue
Output:
- ✅/❌ validation results per package
- 📦 package metadata
- 🔧 installation test results
- 🧪 smoke test results
- 📋 verification summary
- Exit code: 0 (valid), 1 (invalid)
resume-release.fsx
Purpose: Resume failed release from checkpoint
Features:
- Read tracking issue for context
- Identify last successful step
- Validate prerequisites for resume
- Prompt for confirmation
- Resume workflow from appropriate point
- Update tracking issue
Usage:
dotnet fsi .claude/skills/release-manager/resume-release.fsx --issue 219
dotnet fsi .claude/skills/release-manager/resume-release.fsx \
--version 1.0.0 \
--issue 219
dotnet fsi .claude/skills/release-manager/resume-release.fsx \
--issue 219 \
--dry-run
Output:
- 📋 Resume plan
- ✅ Prerequisites check
- ⚠️ Confirmation prompt
- 🔄 Resume actions
- Exit code: 0 (resumed), 1 (cannot resume), 2 (aborted)
GitHub Issue Templates
Release Tracking Issue Template
Location: .claude/skills/release-manager/templates/release-tracking.md
Purpose: Track single release lifecycle
Includes:
- Release metadata (version, date, type)
- Pre-flight checklist
- Execution checklist
- Verification checklist
- Documentation checklist
- Links to workflow runs
- Links to published packages
- Notes section for issues/learnings
Integration with QA Tester
Handoff points:
- After packages published → QA smoke tests
- After installation verified → QA functional tests
- Before closing release → QA sign-off
Communication format:
@skill qa-tester
Release v{version} ready for verification.
**Packages:**
- Morphir.Core v{version}: https://nuget.org/packages/Morphir.Core/{version}
- Morphir.Tooling v{version}: https://nuget.org/packages/Morphir.Tooling/{version}
- Morphir v{version}: https://nuget.org/packages/Morphir/{version}
- Morphir.Tool v{version}: https://nuget.org/packages/Morphir.Tool/{version}
**Test Plan:**
1. Run smoke-test.fsx
2. Test tool installation from NuGet
3. Verify key commands work
4. Check for regressions
**Tracking Issue:** #{issue-number}
Please update tracking issue with results.
QA feedback integration:
- QA adds comment to tracking issue
- Release Manager reviews results
- Issues addressed before closing release
- QA sign-off required for completion
Best Practices
Version Selection
- Follow semantic versioning strictly
- Analyze all changes in [Unreleased]
- Err on side of caution (major vs minor)
- Consult team for breaking changes
- Document rationale in tracking issue
Changelog Management
- Update continuously during development
- Categorize clearly (Added, Changed, Fixed, etc.)
- Be user-focused (not implementation details)
- Reference issues/PRs for traceability
- Mark breaking changes prominently
Release Execution
- Never rush - follow all steps
- Monitor actively - don't set and forget
- Document everything - issues, workarounds, learnings
- Coordinate with QA - don't skip verification
- Update playbook - continuous improvement
Local State Flexibility
- Prefer clean state but don't require it
- Warn users about potential interference
- Offer assistance for state management
- Let users decide their workflow
- Use --ref main to ensure remote execution
Failure Handling
- Stay calm - failures happen
- Diagnose thoroughly - understand root cause
- Document completely - help future releases
- Prevent recurrence - update automation
- Learn continuously - improve process
Documentation
- Write for users - not developers
- Highlight breaking changes - with migration guide
- Show examples - not just lists
- Link to details - don't duplicate docs
- Keep current - update with each release
Troubleshooting
"Version already exists on NuGet"
Cause: Trying to publish same version twice
Solution:
- Check NuGet.org - was previous release successful?
- If successful: Increment version, retry
- If failed: Contact NuGet support to unlist
- Prevention: Better validation in prepare-release.fsx
"E2E tests fail on specific platform"
Cause: Platform-specific bug or flaky test
Solution:
- Review platform-specific logs
- If infrastructure issue: Re-run workflow
- If actual bug: Fix and new release
- If flaky test: Fix test, new release
"NuGet publish timeout"
Cause: Network issue or NuGet.org downtime
Solution:
- Check NuGet.org status
- Wait and retry if transient
- Contact support if persistent
"Workflow run not found"
Cause: Workflow didn't trigger or permissions issue
Solution:
- Check workflow file syntax
- Verify GH_TOKEN permissions
- Check branch protection rules
- Manually trigger:
gh workflow run deployment.yml --ref main
"Local changes might interfere"
Not an error - Just advisory
Options:
- Stash changes:
git stash save "WIP before release"
- Commit changes: Create WIP commit
- Continue anyway: If changes don't affect release
- Let user choose: Their workflow, their decision
References
Continuous Improvement
Automated Retrospective and Feedback System:
The release management skill now includes automated prompts to capture feedback at critical moments:
1. Failure Retrospective (monitor-release.fsx)
When a release fails, the monitoring script automatically:
- Detects the failure
- Prompts: "We noticed the release failed. Are there any changes we could make to the release process to ensure future success?"
- Records feedback in the release tracking issue
- Tracks consecutive failures to identify patterns
How to use:
- Run
monitor-release.fsx as normal
- When failure is detected, you'll be prompted for feedback
- Provide specific, actionable insights about what went wrong
- Feedback is automatically added to the tracking issue
2. Success Feedback (validate-release.fsx)
After three or more consecutive successful releases, the validation script:
- Prompts: "You've had [N] successful releases in a row! 🎉 Would you like to provide feedback on how we can further improve the release process?"
- Records improvement suggestions in the tracking issue
- Resets the counter on any failure
How to use:
- Run
validate-release.fsx after successful releases
- After 3+ consecutive successes, you'll be prompted
- Share what's working well and ideas for further improvement
- Helps identify best practices to formalize
3. Process Change Detection (prepare-release.fsx)
During release preparation, the script analyzes changes since the last release:
- Detects modifications to:
.github/workflows/deployment.yml.claude/skills/release-manager/ scriptsAGENTS.md and .agents/release-management.md
- Prompts: "We see changes to [N] release process files. Would you like to update or add to our release playbooks based on these changes?"
- Guides you to update relevant documentation
How to use:
- Run
prepare-release.fsx before starting a release
- Review detected changes to release process files
- If prompted, provide context about why changes were made
- Update documentation: skill.md, README.md, AGENTS.md
Release History Tracking
The system maintains a release history file (.release-history.json) to:
- Track consecutive successes and failures
- Store release metadata (version, date, status)
- Enable pattern detection across releases
- Support retrospective analysis
Manual history queries (via release-history.fsx):
#load "release-history.fsx"
open ReleaseHistory
// Check consecutive successes
let successes = getConsecutiveSuccesses()
// Get last N releases
let recent = getLastNReleases 5
// Add custom release record
addRelease "1.0.0" Success (Some 219) (Some "Smooth release, no issues")
Best Practices for Feedback
When providing failure feedback:
- Be specific about what failed and why
- Suggest concrete improvements
- Reference specific steps or tools
- Consider both technical and process issues
When providing success feedback:
- Highlight what's working well
- Suggest incremental improvements
- Share efficiency gains discovered
- Identify reusable patterns
When noting process changes:
- Explain the motivation for changes
- Document expected benefits
- Note any risks or tradeoffs
- Update playbooks immediately
After Each Release
- Review what went well
- Document what went wrong (automated prompt on failure)
- Update automation scripts
- Enhance playbook with new learnings
- Share learnings with team (via feedback in issues)
- Update AGENTS.md if needed
Metrics to track:
- Time to release
- Failed releases (count and reasons) - automatically tracked
- Consecutive successes - automatically tracked
- Manual interventions needed
- Documentation completeness
- QA issues found post-release
- Feedback response rate
Goal: Fully automated, reliable, repeatable releases with flexible workflows and continuous improvement driven by real-world feedback.
Remember: Releases represent the project's quality and professionalism. Take your time, follow the process, document everything, and continuously improve. Be flexible with local state while maintaining strict standards for remote execution. Users depend on reliable releases.
The retrospective system helps build a culture of continuous improvement by capturing insights at the moments they matter most.
