finalize-phase

<objective>
Complete feature/epic workflow, generate walkthrough (epics only), update roadmap, archive artifacts, and preserve knowledge after deployment. Ensures clean workflow closure with self-improving workflow system.

This skill orchestrates the /finalize phase, the final step after successful deployment to production, direct-prod, or local build.

**For Epic Workflows (v5.0+)**:

- Generate comprehensive walkthrough.md with velocity metrics, sprint results, lessons learned
- Run post-mortem audit with pattern detection (after 2-3 epics)
- Offer workflow healing with improvement recommendations
- Detect patterns for custom skills/commands generation

**For Feature Workflows**:

- Standard finalization (roadmap, artifacts, docs, branches)

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

1. Run post-mortem audit - Final effectiveness analysis with improvement recommendations
2. Offer workflow healing - Apply discovered improvements with user approval

**All Workflows** (features + epics):

1. Update roadmap - Move to "Shipped" with completion date, version, production URL
2. Archive artifacts - Verify all phase artifacts in specs/NNN-slug/ or epics/NNN-slug/
3. Update documentation - README, CHANGELOG, user guides (if applicable)
4. Clean up branches - Delete feature branch locally and remotely
5. Commit finalization - Small commit documenting workflow closure

Key principles:

- Clean closure preserves knowledge and enables learning
- Epic walkthroughs enable self-improving workflow system
- Pattern detection (after 2-3 epics) suggests custom automation
  </quick_start>

<prerequisites>
Before beginning finalization:
- Deployment completed successfully (/ship-prod, /deploy-prod, or /build-local done)
- Ship report generated (ship-summary.md exists)
- All phase artifacts present in specs/NNN-slug/
- Git working tree clean (all changes committed)

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**:

```bash
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**:

1. **Gather all epic artifacts**:

   - epic-spec.xml (epic specification)
   - research.xml (research phase output)
   - plan.xml (plan phase output with meta-prompting)
   - sprint-plan.xml (task breakdown with dependency graph)
   - state.yaml (state tracking across phases)
   - audit-report.xml (workflow effectiveness analysis)
   - preview-report.xml (manual testing decision)
   - Sprint results from epics/NNN-slug/sprints/\*/

2. **Calculate velocity metrics**:

   - Expected parallelization multiplier (from sprint-plan.xml)
   - Actual parallelization multiplier (from audit-report.xml)
   - Time saved in hours (parallel vs sequential execution)
   - Duration from start to completion

3. **Extract key information**:

   - Epic goal and success metrics
   - Phases completed with timestamps
   - Sprint execution results (status, tasks, duration, contracts, tests)
   - Validation results (optimization, preview decision)
   - Key files modified
   - Next steps (enhancements, technical debt, monitoring needs)

4. **Generate walkthrough.xml and walkthrough.md**:

   - Use template: `.spec-flow/templates/walkthrough.xml`
   - Populate with metrics, sprint results, lessons learned
   - Write both machine-readable (XML) and human-readable (Markdown) versions

5. **Run post-mortem audit**:

   - Invoke `/audit-workflow --post-mortem`
   - Analyze velocity accuracy (expected vs actual)
   - Detect bottlenecks and inefficiencies
   - Generate improvement recommendations

6. **Pattern detection** (if 2+ epics completed):

   - Analyze patterns across completed epics
   - Detect code generation patterns (service boilerplate repeated 3x)
   - Detect architectural patterns (all services use DI + Repository)
   - Detect workflow patterns (always clarify auth approach)
   - Suggest custom skills/commands if confidence ≥80%

7. **Offer workflow healing**:

   - Display immediate improvements from audit recommendations
   - Categorize by priority (immediate vs deferred)
   - Offer `/heal-workflow` to apply improvements
   - Save deferred improvements for pattern-based optimization

8. **Commit walkthrough**:

```bash
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>"
```

9. **Present walkthrough summary** to user with:
   - Velocity metrics (expected