docs/interactive-ux/SCOPE.md

Interactive UX scope

Scope model

Features are grouped by implementation risk and product leverage.

• MVP: should be built first; high value, technically feasible, foundational.
• V2: valuable after the core supervised editing loop exists.
• Research/backlog: plausible, but higher risk or dependent on stronger state/model infrastructure.

MVP scope and status

1. Constraint-aware cluster editing

Status: partial / foundation implemented.

Implemented:

• Move hit/sample to cluster.
• Pull hit/sample out into a new cluster.
• Create must-link, cannot-link, and force-cluster constraints.
• Preserve explicit edits in supervision_state.json across reload.
• Generate basic suggestions after edits.

Remaining:

• True local neighborhood reclustering from cached feature vectors.
• Constraint violation detection.
• Edited artifact re-export.

2. Lock confirmed clusters

Status: implemented.

Implemented:

• Lock/unlock cluster.
• Persist lock state.
• Show lock state in the cluster board and target cluster control.
• Confidence scoring accounts for locked state.

Remaining:

• Prevent future batch reruns from violating locked cluster identity through deterministic replay.

3. Outlier-first review queue

Status: implemented.

Implemented:

• Confidence score per hit and cluster.
• Review list sorted by uncertainty priority.
• Quick actions: accept, favorite, move, pull out, suppress.

Remaining:

• Split/restore/batch actions.
• Expected-impact scoring using feature margin and reconstruction contribution.

4. Confidence-weighted UI

Status: implemented.

Implemented:

• Confidence per hit and cluster.
• Low-confidence row emphasis.
• Suppressed rows recede.
• State summary badges.

5. Click-to-add missed onset

Status: not implemented.

Current waveform clicks audition existing hits. Add-onset mode is the next direct correction primitive.

6. Bleed suppression examples

Status: partial.

Implemented:

• Mark selected hit as bleed/noise.
• Store suppress-pattern.
• Generate similar suppression suggestions.

Remaining:

• Region brush.
• Restore suppressed hits.
• Exclude suppressed hits from supervised export.

7. Explain this cluster

Status: implemented.

Implemented:

• Representative ID.
• Members/outliers.
• Confidence reasons.
• Label distribution.
• Relevant constraints.
• Locked/suppressed counts.

V2 scope

1. Predictive batch questions

Status: partial.

Basic suggestions exist. Exact diff previews, grouped approval UX, and richer reasoning are not complete.

2. Live counterfactual previews

Status: not implemented.

3. Auto-clean this family

Status: not implemented.

4. Multi-resolution semantic clustering

Status: not implemented.

5. Run-to-run preference memory

Status: not implemented.

Research/backlog scope

Unchanged from design intent:

• Reconstruction-error-driven correction.
• Drag clusters in semantic space.
• Cluster gravity / physics metaphor.
• Context-aware classification.
• Teach mode across songs.

Explicitly out of scope for MVP

• Realtime Demucs.
• Training neural models from scratch.
• Cloud multi-user collaboration.
• DAW plugin integration.
• Full Ableton/Logic export format support.
• Automatic perfect drum transcription claims.

MVP acceptance criteria status

Target loop:

cached stem is analyzed
→ clusters appear
→ uncertain items are prioritized
→ user moves one wrong hit
→ system stores a constraint
→ affected state recomputes
→ related mistakes are suggested
→ locked clusters remain stable in state
→ semantic decisions reload reproducibly

Status: mostly achieved for semantic state.

Not achieved yet:

→ edited state can be exported reproducibly as updated WAV/MIDI/ZIP artifacts
→ local feature reclustering updates related hits without manually accepting suggestions

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.