# Handoff 2026-02-02 — Segmentation Storyboard MVP (R² in Global Time)

## Purpose
Implement a **new, additive** visualization called the **Segmentation Storyboard**.

This plot is intended to make the piecewise, backward-growing window algorithm understandable at a glance by:
- re-embedding fit-quality (R²) into the **global signal time domain**, and
- making **handoff boundaries** (piece segmentation cut points) visually explicit.

This is an MVP. Keep it minimal and diagnostic-first.

---

## Non-Destructive Requirement

- Do **not** replace or modify existing plots:
  - existing R² vs Δt diagnostic traces
  - existing inverted-x Δt storytelling view

The storyboard is a **new output** produced alongside the others.

---

## Plot Definition

### Single Axis
- One plot, one axis
- No subplots

### Axes
- x-axis: **global time** (seconds)
  - Use the same time base `t[]` already used for the signal/envelope analysis.
- y-axis: **R²**

### Series
For each piece `p in [0 .. n_pieces-1]`:

1) **R² trace mapped into global time**

- Each fit window is defined by indices `(i_start, i_end)`.
- The corresponding R² value is `r2(i_start, i_end)`.

**Map each point to global time as:**

- `x_p = t[i_start]`  (global start time of the window)
- `y_p = r2(i_start, i_end)`

Plot `(x_p, y_p)` as a line trace labeled:
- `Storyboard R² — piece {p}`

**Domain behavior (important):**
- piece 0 will span far back toward earlier time until degradation
- piece 1 starts at the handoff boundary of piece 0
- etc.

2) **Handoff boundary markers**

For each boundary between piece `p` and the next piece:
- boundary index: `i_boundary[p]` (the same index used to update `i_end` for the next piece)
- boundary time: `t_boundary[p] = t[i_boundary[p]]`

Add a vertical line at `t_boundary[p]` labeled:
- `Handoff {p}→{p+1}`

(Example for n=2: one boundary line labeled `Handoff 0→1`.)

---

## Semantics (Must Be True)

- The storyboard x-axis is **global**.
- Each curve point corresponds to a real window start time.
- Boundary lines mark the exact time where the algorithm “passes the ball” to the next piece.

This plot is not about window duration Δt.
It is explicitly about **where in time each piece’s window-extension quality lives**.

---

## Labeling Requirements

- Title should include context similar to other plots, e.g.:
  - `Segmentation Storyboard — Fit Quality vs Time (fn=... Hz)`
- x-label: `Time t (s)`
- y-label: `R² score`

Legend entries must be explicit:
- `Storyboard R² — piece 0`
- `Storyboard R² — piece 1`
- `Handoff 0→1`

Avoid generic `Breakpoint 0/1` naming in this plot.
This plot is about **handoff semantics**.

---

## Data/Implementation Notes

- This should reuse existing computed artifacts:
  - the window start indices `i_start` already enumerated per piece
  - the computed R² for each window
  - the selected boundary index per piece
  - the global time base `t[]`

- Do not recompute signal processing solely for plotting.

- Ensure x-values are monotonic within each piece trace:
  - As windows expand backward, `i_start` decreases, so `t[i_start]` decreases.
  - If plotting left-to-right increasing time, you may need to sort by `x_p`.

---

## MVP Scope (Explicit)

Include only:
- piecewise R² curves in global time
- handoff boundary vertical lines

Do NOT include (yet):
- envelope overlay
- ownership bands
- shaded validity regions
- additional metrics (curvature, slope, residuals)

Those are future extensions.

---

## Success Criteria

Given the storyboard plot, a viewer should be able to answer in seconds:

1) Where does piece 0 stop being responsible?
2) Where does piece 1 begin?
3) How does R² behave as each piece extends earlier in time?

---

## Status

- MVP storyboard concept: **locked**
- Ready for OpenCode implementation

