serato-doctor/docs/design/diagnostic-drilldowns.md

Diagnostic Drill-Downs

Problem

Aggregate health numbers are useful, but DJs need to understand what is behind each number before they can trust it. A count like "60 missing tracks" should be clickable enough to answer: which tracks, which saved paths, and why did Serato Doctor count them?

Architecture

The health engine remains responsible for aggregate scoring. The web layer adds a separate details payload beside the existing health report so the UI can show examples without changing the core score model.

The drill-down payload is intentionally capped. Serato Doctor should explain the finding quickly in the local browser, not dump an entire user library into the page.

Edge Cases

• Smart/dynamic crate references stay excluded from old-reference scoring.
• The same missing filename can appear more than once in Serato's database.
• Duplicate filename and cloud-conflict groups are informational only.
• Suggested matches remain read-only evidence and must never trigger repair.
• Empty drill-downs should feel reassuring, not broken.

Testing

• Web analysis should include detail sections for old crate references, suggested matches, unused tracks, duplicates, cloud conflicts, broken symlinks, and missing Serato database tracks.
• Static assets should expose clickable diagnostic hooks.
• Browser behavior should be verified manually when the local browser policy allows access to the development server.