finalize

# /finalize — Post-Deployment Finalization (Thin Wrapper)

> **v11.0 Architecture**: This command spawns the isolated `finalize-phase-agent` via Task(). Documentation and archival runs in isolated context.

<context>
**Active Feature**: !`ls -td specs/[0-9]*-* 2>/dev/null | head -1 || echo "none"`

**Interaction State**: !`cat specs/*/interaction-state.yaml 2>/dev/null | head -10 || echo "none"`
</context>

<objective>
Spawn isolated finalize-phase-agent to complete post-deployment documentation and archival.

**Architecture (v11.0 - Phase Isolation):**
```
/finalize → Task(finalize-phase-agent) → CHANGELOG, walkthrough, archive
```

**Agent responsibilities:**
- Generate CHANGELOG.md entry
- Update README.md if user-facing changes
- Create walkthrough.md (comprehensive for epics)
- Create GitHub release
- Archive feature to completed/
- Clean up feature branch

**Execution model**:
- **Idempotent**: Safe to re-run; completed tasks are skipped
- **Deterministic**: No prompts, no editors
- **Tracked**: Every step logged with clear progress indicators

**Workflow position**: `implement → optimize → validate → ship → finalize`
</objective>

## Legacy Context (for agent reference)

<legacy_context>
Current workflow state: !`cat specs/*/state.yaml 2>/dev/null | grep -E '(feature\.|deployment\.production\.|version:)' | head -20`

Recent production deployment: !`yq -r '.deployment.production | "URL: \(.url // "N/A"), Date: \(.completed_at // "N/A"), Status: \(.status // "unknown")"' specs/*/state.yaml 2>/dev/null`

Required tools check: !`for c in gh jq yq git python; do command -v "$c" >/dev/null 2>&1 && echo "✅ $c" || echo "❌ $c"; done`
</legacy_context>

<process>
1. **Check prerequisites** - Verify gh, jq, yq, git, python are installed and gh is authenticated

2. **Execute finalization workflow** via spec-cli.py:

   ```bash
   python .spec-flow/scripts/spec-cli.py finalize
   ```

   The finalize-workflow.sh script performs:

   a. **Epic workflows only** (v5.0+):

   - Generate walkthrough.md with velocity metrics
   - Calculate sprint results and lessons learned
   - Run pattern detection across completed epics (if 2+ completed)
   - **Auto-offer workflow healing** (v10.14+):
     - Check `.spec-flow/analytics/patterns.json` for recommendations
     - If `avg_blockers > 3` or `avg_duration > 14 days`, prompt user:

     ```
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     Pattern Analysis Suggests Improvements
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

     Detected patterns across {N} completed epics:
     - Average blockers per epic: {avg_blockers}
     - Average duration: {avg_duration} days
     - Common blocker themes: {themes}

     Recommendations:
     {recommendations from patterns.json}
     ```

     Use AskUserQuestion:
     - Question: "Apply workflow improvements?"
     - Header: "Healing"
     - Options:
       - "Yes" - Run `/heal-workflow` to create improvement issues
       - "No" - Skip healing, continue finalization

     **If user selects "Yes"**:
     - Invoke `/heal-workflow` via SlashCommand tool
     - Continue to standard finalization after healing completes

   b. **Standard finalization** (all workflows):

   - Update CHANGELOG.md (Keep a Changelog format)
   - Update README.md (Shields.io version badge + features)
   - Generate help article at docs/help/features/{slug}.md
   - Update API docs (conditional if endpoints changed)
   - Close current milestone, create next milestone
   - Update roadmap issue to "shipped" status
   - Update GitHub Release with production deployment info
   - Commit and push documentation changes
   - Cleanup feature branch (safe delete if merged)
   - **Archive workflow artifacts** (v9.3+):
     - Move all planning artifacts to {workspace}/completed/
     - Epic: epic-spec.md, plan.md, sprint-plan.md, tasks.md, NOTES.md, research.md, walkthrough.md
     - Feature: spec.md, plan.md, tasks.md, NOTES.md
     - state.yaml remains in root (for metrics/history)

   - **Cleanup worktree** (v11.8 - if worktrees.cleanup_on_finalize is true):
     - Check if current feature/epic has a worktree
     - If cleanup_on_finalize is enabled (default: true):
       ```bash
       CLEANUP_ENABLED=$(bash .spec-flow/scripts/utils/load-preferences.sh --key "worktrees.cleanup_on_finalize" --default "true" 2>/dev/null || echo "true")
       if [ "$CLEANUP_ENABLED" = "true" ]; then
         WORKFLOW_TYPE=$(yq eval '.workflow_type // "feature"' "$WORKSPACE_DIR/state.yaml" 2>/dev/null)
         SLUG=$(basename "$WORKSPACE_DIR")
         WORKTREE_PATH=$(bash .spec-flow/scripts/bash/worktree-context.sh get-worktree "$WORKFLOW_TYPE" "$SLUG" 2>/dev/null)

         if [ -n "$WORKTREE_PATH" ] && [ -d "$WORKTREE_PATH" ]; then
           echo "Cleaning up worktree: $WORKTREE_PATH"
           bash .spec-flow/scripts/bash/worktree-manager.sh remove "$SLUG" --force
         fi
       fi
       ```
     - Output: "Worktree cleaned up. Returning to root repository."

3. **Review summary output** - Verify all tasks completed successfully

4. **Next steps** (displayed in output):
   - Review documentation accuracy
   - Announce release (social media, blog, email)
   - Monitor user feedback and error logs
   - Plan next feature from roadmap

5. **Offer next feature (Studio Mode)** - Auto-continue workflow loop:

   After successful finalization, check if more work is available:

   ```bash
   # Count remaining roadmap items
   NEXT_COUNT=$(gh issue list --label "status:next,type:feature" --json number --jq 'length' 2>/dev/null || echo "0")
   BACKLOG_COUNT=$(gh issue list --label "status:backlog,type:feature" --json number --jq 'length' 2>/dev/null || echo "0")
   TOTAL_REMAINING=$((NEXT_COUNT + BACKLOG_COUNT))
   ```

   **If roadmap is empty** (TOTAL_REMAINING = 0):
   ```
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Roadmap Complete!
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

   No more issues with status:next or status:backlog.
   All planned work has been co