finalize-phase

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:

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:

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 vs actual, time saved)
   • Sprint results (status, tasks, duration, tests)
   • Quality metrics (audit score, phase efficiency, parallelization score)
   • What worked / what struggled / lessons learned
   • Improvement recommendations (if any)
   • Pattern detection results (if 2+ epics completed)

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.

## 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

# List all artifacts in feature directory
ls -la specs/NNN-slug/

# Should see all required files
# No temporary files (.tmp, .bak, etc.)

## 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

## [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)

# 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

# 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

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/"

finalization:
  status: completed
  completion_date: 2025-10-21
  version: v1.3.0
  artifacts_archived: true
  documentation_updated: true
  branches_cleaned: true

Feature deploys to production
/finalize skips roadmap update
Roadmap still shows feature "In Progress"
6 months later: "Did we ship this? When?"

Feature deploys to production
/finalize updates roadmap immediately
Roadmap shows "Shipped 2025-10-21, v1.3.0"
6 months later: Clear historical record

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)

Ship feature, update README immediately
README: "Student Progress Dashboard - Track completion"
User discovers feature organically from README

git branch -a
# Shows 87 feature branches (only 3 active)
# Which branches are safe to delete? Unknown.

git branch -a
# Shows 3 feature branches (all active)
# Clear signal: current work only

Update roadmap, README, CHANGELOG
Git status: 3 modified files
Never commit (lose changes on machine wipe)

Update roadmap, README, CHANGELOG
git commit -m "chore: finalize feature (v1.3.0)"
Clear git history marker: finalization happened

Ship feature, delete spec.md and plan.md
6 months later: "Why did we implement it this way?"
Answer: Unknown (artifacts deleted)

Ship feature, archive all artifacts
6 months later: "Why did we implement it this way?"
Answer: Check specs/042-.../spec.md (clear rationale)