docs/interactive-ux/FEATURE_REQUIREMENTS.md

# Interactive UX feature requirements

## Goal

Add interactions that make extraction faster and more accurate by converting user actions into reusable supervision signals.

The application should progressively converge toward the user's intended drum vocabulary with minimal manual cleanup.

## Success criteria

- User corrections affect more than the single edited item when safe.
- Explicit user intent is preserved across reclustering and reloads.
- The system surfaces uncertain/high-leverage items before stable ones.
- The user can understand why items are grouped or separated.
- Cached stem/source analysis can be reused while downstream parameters update quickly.
- The UI supports fast audition, correction, locking, and export loops.

## Current implementation summary

Implemented now:

- Persistent semantic state per run: `supervision_state.json`.
- Event log and constraint store.
- Confidence-weighted hit/cluster state.
- Outlier-first review queue.
- Move hit to cluster.
- Pull hit into new cluster.
- Lock/unlock cluster.
- Suppress hit as bleed/noise.
- Accept/favorite selected hit.
- Suggestion inbox with accept/reject.
- Cluster explanation endpoint and UI drawer.
- Undo for the last semantic edit.

Partially implemented:

- Local recomputation is currently semantic-state recomputation, not full feature-neighborhood reclustering.
- Suggestions are heuristic and preview-count based, not full diff previews.
- Favorite/pin changes semantic representative and supervised export honors it when generating the edited sample pack.
- Confidence scoring is heuristic, not feature-margin/stability based.

Implemented in Pass 5 where noted; remaining items listed below:

- Click-to-add missed onset.
- Restore suppressed hit.
- Supervised re-export from edited state.
- Counterfactual parameter previews.
- Reconstruction-error correction.
- Teach mode across songs.

## Functional requirements and status

### FR-001: Cluster move as positive supervision

Status: **implemented as semantic-state edit**.

When a user moves a hit/sample into a cluster, the backend creates `force-cluster` and, when a representative exists, `must-link`. State confidence is recomputed and similar hit suggestions may be generated.

Remaining gap: true local feature-neighborhood reclustering and exact before/after diff preview.

### FR-002: Pull-out as negative supervision

Status: **implemented as semantic-state edit**.

Pulling a hit out creates a new user cluster, records a `cannot-link` to the source representative when possible, and stores a `force-cluster` assignment for the new cluster.

Remaining gap: automatic split suggestions are heuristic and do not yet run constrained reclustering.

### FR-003: Lock confirmed cluster identity

Status: **implemented**.

Clusters can be locked/unlocked through the API/UI. Lock state is persisted and influences confidence.

Remaining gap: future full reruns do not yet replay locks into batch clustering.

### FR-004: Outlier-first review queue

Status: **implemented**.

The backend returns a `review_queue` sorted by low confidence, singleton status, review status, and suppression state. The UI renders the queue and lets the user select/audition items.

Remaining gap: expected-impact ranking should eventually use feature margin and reconstruction contribution.

### FR-005: Confidence-weighted visual emphasis

Status: **implemented**.

Hit rows display confidence and flags. Low-confidence rows get emphasis; suppressed rows visually recede.

### FR-006: Click-to-add missed onset

Status: **not implemented**.

Current waveform click auditions the nearest existing hit only.

Required next behavior:

- Add `force-onset` constraint at selected time.
- Slice candidate hit from cached `stem.wav`.
- Classify and assign locally.
- Store it as a forced hit in `supervision_state.json`.

### FR-007: Bleed brush / false-positive suppression

Status: **implemented for selected hits; brush region not implemented**.

Selected hits can be suppressed as bleed/noise. The system stores `suppress-pattern` and proposes similar suppressions.

Remaining gap: region brush, restore, and supervised export exclusion.

### FR-008: Favorite/pin sample optimization

Status: **partial**.

Favorite action records `pin-representative` and updates the semantic representative. Exported WAV/ZIP does not yet change.

### FR-009: Explain cluster

Status: **implemented**.

Cluster explanation includes representative, hit counts, confidence reasons, label distribution, outliers, and relevant constraints.

### FR-010: Predictive batch questions

Status: **partial**.

Suggestions exist for move/split/suppress patterns and can be accepted/rejected. They do not yet show exact diff previews.

### FR-011: Live counterfactual parameter preview

Status: **not implemented**.

### FR-012: Reconstruction-error correction

Status: **not implemented**.

## Non-functional requirements and status

### NFR-001: Reversibility

Status: **implemented for semantic edits** via undo stack.

### NFR-002: Explainability

Status: **partial**. Events, constraints, confidence reasons, and cluster explanations are visible. Suggestion diff previews are not yet implemented.

### NFR-003: Local recomputation first

Status: **partial**. Current recomputation is cheap semantic-state recomputation. True local feature reclustering remains open.

### NFR-004: Cached preprocessing

Status: **partial**. Stems/source loads are cached and hit audio is exported. Feature-vector caching is still open.

### NFR-005: Deterministic replay

Status: **partial**. Constraints/events persist and can be reloaded. A dedicated replay command/export pipeline is still open.

### NFR-006: No silent override of explicit user intent

Status: **implemented in current semantic layer**. Explicit moves, locks, suppressions, and favorites persist unless undone or explicitly changed.


## Pass 5 implementation status

Implemented after initial alignment:

- supervised edited-state export under `supervised/`,
- add-onset waveform mode backed by `POST /api/jobs/{job_id}/hits/force-onset`,
- suppressed-hit restore backed by `POST /api/jobs/{job_id}/hits/{hit_id}/restore`,
- exact suggestion diff previews in API state and UI,
- validation via `scripts/test_supervised_export_and_force_onset.py`.

Still open:

- cluster merge/relabel/split workflows,
- cached feature-vector local reclustering,
- edited-vs-original comparison,
- browser-level UI tests.