Completes feature/epic workflows after deployment with comprehensive walkthrough generation for epics (v5.0+), roadmap updates, artifact archival, documentation, and branch cleanup. Use after /ship-prod, /deploy-prod, or /build-local completes, or when user asks to finalize. (project)
This skill orchestrates the /finalize phase, the final step after successful deployment to production, direct-prod, or local build.
For Epic Workflows (v5.0+):
For Feature Workflows:
Inputs: Deployed feature/epic, phase artifacts, ship report, state.yaml Outputs: walkthrough.md (epics only), updated roadmap, archived artifacts, updated documentation Expected duration: 10-15 minutes (features), 20-30 minutes (epics with walkthrough) </objective>
<quick_start> After deployment completes, finalize the workflow:
Epic Workflows (NEW in v5.0): 0. Generate walkthrough - Comprehensive epic summary with velocity metrics, sprint results, lessons learned, pattern detection
All Workflows (features + epics):
Key principles:
If deployment incomplete, return to /ship phase. </prerequisites>
<workflow> <step number="0"> **Epic Walkthrough Generation** (Epic workflows only - NEW in v5.0)Detect epic vs feature workflow and generate comprehensive walkthrough for epics.
Detection:
if [ -f "epics/*/epic-spec.xml" ]; then
WORKSPACE_TYPE="epic"
EPIC_DIR=$(dirname "epics/*/epic-spec.xml")
else
WORKSPACE_TYPE="feature"
# Skip to Step 1 (standard finalization)
continue
fi
If feature workflow: Skip this step entirely, proceed to Step 1
If epic workflow: Generate walkthrough before standard finalization
Walkthrough Generation Pipeline:
Gather all epic artifacts:
Calculate velocity metrics:
Extract key information:
Generate walkthrough.xml and walkthrough.md:
.spec-flow/templates/walkthrough.xmlRun post-mortem audit:
/audit-workflow --post-mortemPattern detection (if 2+ epics completed):
Offer workflow healing:
/heal-workflow to apply improvementsCommit walkthrough:
git add epics/*/walkthrough.xml
git add epics/*/walkthrough.md
git add epics/*/audit-report.xml
git commit -m "docs: generate epic walkthrough
[EPIC SUMMARY]
Epic: ${epic_slug}
Duration: ${duration_hours}h
Velocity: ${velocity_multiplier}x (saved ${time_saved}h)
[SPRINTS COMPLETED]
Total: ${total_sprints}
Execution: ${execution_strategy}
Tasks: ${tasks_completed}/${total_tasks}
[QUALITY METRICS]
Audit Score: ${audit_score}/100
Phase Efficiency: ${phase_efficiency}/100
[LESSONS LEARNED]
- What worked: ${what_worked_summary}
- What struggled: ${what_struggled_summary}
{IF recommendations > 0}
Improvement recommendations: ${recommendations_count}
Run /heal-workflow to apply improvements
{ENDIF}
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"
After walkthrough complete: Proceed to Step 1 (standard finalization)
Validation: For epics, walkthrough.xml and walkthrough.md exist in epics/NNN-slug/
See reference.md for epic walkthrough generation details. </step>
<step number="1"> **Update Roadmap**Move feature from "In Progress" to "Shipped" section in roadmap.
Actions:
.spec-flow/memory/roadmap.mdRequired information:
Example:
## Shipped
### Student Progress Dashboard (v1.3.0) - Shipped 2025-10-21
- **Production URL**: https://app.example.com/students/progress
- **Ship Report**: specs/042-student-progress-dashboard/ship-summary.md
- **Release Notes**: CHANGELOG.md#v1.3.0
- **Impact**: Teachers can now track student progress with completion rates and time spent
Validation: Feature appears in "Shipped" section with all required details.
See reference.md for roadmap update checklist. </step>
<step number="2"> **Archive Artifacts**Verify all workflow artifacts archived in specs/NNN-slug/ directory.
Required artifacts checklist:
Optional artifacts:
Validation steps:
# List all artifacts in feature directory
ls -la specs/NNN-slug/
# Should see all required files
# No temporary files (.tmp, .bak, etc.)
If artifacts missing:
See reference.md for complete artifact checklist. </step>
<step number="3"> **Update Documentation**Update user-facing documentation for shipped feature.
README.md updates (if user-facing feature):
## Features
- **Student Progress Dashboard** - Track student completion rates and time spent
- View individual student progress
- Filter by class, subject, or time period
- Export progress reports to CSV
CHANGELOG.md updates:
## [1.3.0] - 2025-10-21
### Added
- Student progress dashboard with completion tracking
- CSV export for progress reports
- Filtering by class, subject, and time period
### Changed
- Improved dashboard load time from 3s to 1.2s
### Fixed
- Fixed timeout issue with large datasets (pagination added)
User guides (for complex features):
Validation: Documentation accurately reflects shipped feature.
See reference.md for documentation standards. </step>
<step number="4"> **Clean Up Branches**Delete feature branch locally and remotely (if applicable).
Local branch deletion:
# Verify branch is merged
git branch --merged main | grep feature/042-student-progress-dashboard
# Delete local branch
git branch -d feature/042-student-progress-dashboard
Remote branch deletion (if pushed to remote):
# Delete remote branch
git push origin --delete feature/042-student-progress-dashboard
# Verify deletion
git branch -r | grep feature/042-student-progress-dashboard # Should return nothing
If branch not merged:
git branch -D feature/...Validation: Feature branch no longer exists locally or remotely.
See reference.md for branch cleanup guidelines. </step>
<step number="5"> **Commit Finalization**Create small commit documenting workflow closure.
Commit format:
git add .spec-flow/memory/roadmap.md README.md CHANGELOG.md
git commit -m "chore: finalize student-progress-dashboard (v1.3.0)
Updated roadmap, README, and CHANGELOG
Archived artifacts in specs/042-student-progress-dashboard/"
Commit message format:
chore (finalization is housekeeping)finalize [feature-name] ([version])Update state.yaml:
finalization:
status: completed
completion_date: 2025-10-21
version: v1.3.0
artifacts_archived: true
documentation_updated: true
branches_cleaned: true
Validation: Finalization commit pushed to main branch.
See reference.md for commit best practices. </step> </workflow>
<validation> After finalization phase, verify:Workflow is now cleanly closed and ready for retrospective analysis. </validation>
<anti_patterns> <pitfall name="roadmap_not_updated"> ❌ Don't: Skip roadmap update, leave feature in "In Progress" ✅ Do: Always move to "Shipped" with completion date and links
Why: Roadmap becomes stale and inaccurate. Team loses visibility into what shipped and when.
Impact:
Example (bad):
Feature deploys to production
/finalize skips roadmap update
Roadmap still shows feature "In Progress"
6 months later: "Did we ship this? When?"
Example (good):
Feature deploys to production
/finalize updates roadmap immediately
Roadmap shows "Shipped 2025-10-21, v1.3.0"
6 months later: Clear historical record
Why: Knowledge loss compounds over time. Users can't discover features if not documented.
Impact:
Example (bad):
Ship feature, skip README update
3 months later: User asks "Do we have progress tracking?"
Answer: "Yes, we shipped that 3 months ago" (not documented)
Example (good):
Ship feature, update README immediately
README: "Student Progress Dashboard - Track completion"
User discovers feature organically from README
Why: Branch clutter makes it hard to find active work.
Impact:
Example (bad):
git branch -a
# Shows 87 feature branches (only 3 active)
# Which branches are safe to delete? Unknown.
Example (good):
git branch -a
# Shows 3 feature branches (all active)
# Clear signal: current work only
Why: Finalization changes should be tracked in git history.
Impact:
Example (bad):
Update roadmap, README, CHANGELOG
Git status: 3 modified files
Never commit (lose changes on machine wipe)
Example (good):
Update roadmap, README, CHANGELOG
git commit -m "chore: finalize feature (v1.3.0)"
Clear git history marker: finalization happened
Why: Artifacts contain valuable context for future maintenance.
Impact:
Example (bad):
Ship feature, delete spec.md and plan.md
6 months later: "Why did we implement it this way?"
Answer: Unknown (artifacts deleted)
Example (good):
Ship feature, archive all artifacts
6 months later: "Why did we implement it this way?"
Answer: Check specs/042-.../spec.md (clear rationale)
<best_practices> <practice name="immediate_finalization"> Run /finalize immediately after deployment succeeds:
Result: Accurate documentation, fewer missed steps </practice>
<practice name="complete_artifact_checklist"> Use complete artifact checklist from reference.md:Result: Complete archival, no lost context </practice>
<practice name="user_facing_documentation"> Always update README and CHANGELOG for user-facing features:Result: Feature discoverability, clear version history </practice>
<practice name="clean_branch_hygiene"> Delete merged branches immediately:Result: Clear signal of active development, reduced clutter </practice>
<practice name="explicit_finalization_commit"> Create explicit commit documenting workflow closure:Result: Clear git history marker, auditable finalization </practice> </best_practices>
<success_criteria> Finalization phase complete when:
Workflow is cleanly closed and ready for retrospective analysis. </success_criteria>
<quality_standards> Good finalization:
Bad finalization:
Issue: Missing artifacts (spec.md, plan.md, etc.) Solution: Check root directory, temp folders, or regenerate if possible. Document missing in commit.
Issue: Feature branch won't delete (not merged)
Solution: Verify feature deployed successfully, then force delete with git branch -D. Document in commit.
Issue: Unclear what version to use Solution: Check CHANGELOG for next version number, or use deployment date as version (v2025.10.21)
Issue: Don't know what to put in CHANGELOG Solution: Review ship-summary.md and release-notes.md for user-facing changes. Focus on Added/Changed/Fixed. </troubleshooting>
<reference_guides> Finalization procedures:
Examples:
Workflow closure: After finalization completes, feature workflow is closed. Retrospective analysis can begin to learn from past work. </reference_guides>
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer