Generated from
cat-harness/skills/process/workflow/release-epic-planning.md— do not edit here.
Release epic planning
A release epic groups all the work for a specific release version. This skill governs how to create, structure, and track them.
Epic structure
The beans hierarchy for a release:
epic: "Release v0.2.0"
├── feature: "CRDM Phase 4b prioritization"
│ ├── task: "Add Phase 4b to crdm-requirements-workflow.md"
│ └── task: "Update phase table"
├── feature: "Release lifecycle skills"
│ ├── task: "Create release-lifecycle.md"
│ ├── task: "Create code-review-process.md"
│ └── task: "Create branch-freshness.md"
└── bug: "Fix 7 BPMN isMarkerVisible attributes"
└── task: "Add isMarkerVisible to 5 files"
Bean types in a release context
| Type | Role in release | Granularity |
|---|---|---|
| epic | The release itself | 1 per release |
| feature | A capability area / user story | 1 per feature |
| task | A single PR-sized implementation unit | 1 per PR |
| bug | A defect fix included in the release | 1 per fix |
| milestone | A session-scoped work container | Not release-scoped |
Creating the hierarchy
# 1. Create the release epic
beans create "Release v0.2.0" --type epic
# 2. Create features under it
beans create "CRDM Phase 4b prioritization" --type feature
beans update <feature-id> --parent <epic-id>
# 3. Create tasks under features
beans create "Add Phase 4b to workflow" --type task
beans update <task-id> --parent <feature-id>
Always check before creating — beans create is not idempotent.
See todo-manager.md §”Check before you create”.
Ordering within a release
Apply the Phase 4b formalize-first rule from crdm-requirements-workflow.md:
- Structural/organizational work first
- Process/policy formalization second
- Implementation third
- Visualization/UI last
Within the epic, number features by dependency order. The first feature completed should not depend on any later feature.
Release readiness
Tracking readiness
The beans visualizer (<base>/beans/) shows open beans grouped by epic.
A release is ready when its epic shows 0 open beans.
Readiness checklist
Before moving from draft to pre-release:
- All must-have features resolved (all child beans completed)
- All should-have features either resolved or deferred to next release
- CI green on main (
bun run cat gates) - All changed BPMN diagrams re-rendered
- All changed docs pages regenerated
- Changelog written (see
release-lifecycle.md) - BA has reviewed accumulated changes
Deferring to next release
If a should-have or nice-to-have feature won’t make the release:
# Move the feature bean to the next release epic
beans update <feature-id> --parent <next-epic-id>
Record the deferral reason in the bean body:
beans update <feature-id> --body-append "Deferred to v0.3.0: not blocking v0.2.0"
GitHub milestone integration (optional)
A GitHub milestone can mirror the release epic for stakeholder visibility:
# Create milestone
gh api repos/{owner}/{repo}/milestones --method POST \
-f title="v0.2.0" -f description="Release v0.2.0"
# Assign PRs to milestone
gh pr edit <number> --milestone "v0.2.0"
The milestone’s completion percentage gives stakeholders a progress view without needing access to the beans store.
Cross-domain applicability
| Domain | Epic title | Features |
|---|---|---|
| Code | “Release v0.2.0” | Skills, schemas, pipeline changes |
| Paper | “Publication: Chapter 3 revision” | Section rewrites, figure updates |
| Project | “Deliverable: Phase 1 report” | Analysis sections, appendices |
The hierarchy and readiness tracking are identical.
Rules
- One epic per release — if scope creeps, split the epic
- Features are independently reviewable — each can be a PR
- Tasks are PR-sized — one task, one PR, one review cycle
- Never close an epic without BA approval — the epic is the release
- Deferred features move to the next epic — they are not deleted
Cross-references
release-lifecycle— semver, release types, changelogcode-review-process— review within release context../../skills/sdlc/crdm/crdm-requirements-workflow.md— Phase 4b ordering../../skills/sdlc/sdlc-core/todo-manager.md— bean creation protocol../../skills/sdlc/sdlc-core/bean-coordination.md— cross-session coordination
Processes that run this skill
| process | step(s) that name it |
|---|---|
| Phase 1: Planning | Draft project roadmap, backlog, and sprint cadence |