debug-diagnosis

name	debug-diagnosis
description	MIR pipeline debugging and failure diagnosis for SunoScribe. Use when analyzing bad or empty scores, warnings, failed tasks, missing artifacts, vocal separation issues, F0 or octave errors, beat/downbeat errors, quantization problems, MusicXML/MIDI export failures, RVC quality issues, or when designing admin/debug artifact views.

Debug Diagnosis

Use this skill to diagnose failures by walking the artifact lineage. Do not jump straight to model swapping or prompt changes.

Diagnosis Order

Follow the pipeline order:

MediaAsset -> CanonicalAudio -> StemSet -> F0Track -> NoteCandidateSet -> RhythmGrid -> ScoreRevision -> Exports -> RVC

At each stage, ask:

• Did the expected artifact exist?
• Was the artifact generated by the correct upstream input?
• Does its metadata match the downstream assumption?
• Is the failure visible in a debug plot or warning?

Failure Categories

Classify issues into one primary category:

• media_ingest: unreadable file, wrong duration, failed video extraction, invalid sample rate.
• separation: missing vocals, strong accompaniment leakage, phase or artifact damage.
• f0: octave errors, unvoiced errors, missing fundamentals, unstable vibrato/slide handling.
• note_segmentation: fragmented notes, merged notes, ornaments mistaken for melody.
• rhythm: wrong tempo, tempo double/half, weak downbeat, unstable beat grid.
• quantization: wrong note values, misplaced notes, bad pickup measure handling.
• score_ir: invalid semantic score, missing track, inconsistent note IDs.
• export: MIDI or MusicXML generated from the wrong revision or invalid score data.
• frontend: OSMD rendering, revision selection, artifact listing, or playback issue.
• rvc: bad corrected F0, wrong transpose, model mismatch, converted vocal artifacts, mix imbalance.

Required Evidence

Prefer concrete evidence over broad claims:

• artifact path or ID
• warning text
• confidence value
• small timeline range
• note ID or measure number
• debug image name
• reproduction input

Debug Artifacts

First-version admin/debug views should include:

• waveform
• spectrogram
• vocals/accompaniment previews
• F0 curve with voiced/unvoiced and note candidates
• beat/downbeat markers
• quantized note overlay
• export metadata
• RVC corrected F0 overlay

Output Format

When reporting a diagnosis, use:

Symptom:
Likely stage:
Evidence:
Root cause:
Recommended fix:
Validation:

If evidence is insufficient, state exactly which artifact is missing.

Non-Goals

• Do not recommend RAG for production debugging.
• Do not accept a successful final export as proof of correct analysis.
• Do not tune HMM/DTW/agent prompts before checking the upstream representation.
• Do not hide failure by generating empty or placeholder scores.