ds-systematic-debugging

Trace notebook and SQL output mismatches back to the first broken transformation.

6|Updated Apr 9, 2026
One-click install
npx skills add https://github.com/Khodzitcky-Vl/data-science-ai-superpowers --skill ds-systematic-debugging
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ds-systematic-debugging
Source: https://github.com/Khodzitcky-Vl/data-science-ai-superpowers/tree/main/ds-systematic-debugging
Command: npx skills add https://github.com/Khodzitcky-Vl/data-science-ai-superpowers --skill ds-systematic-debugging

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It resolves conflicts between notebook outputs and warehouse/SQL results by enforcing a disciplined, evidence-first workflow to locate where the numbers first diverge.

Core Features & Use Cases

  • Root-cause-first debugging: Reproduces the mismatch and traces backward through joins, filters, windowing, and unit alignment without applying speculative fixes.
  • Phase-based investigation: Guides you through root-cause investigation, pattern analysis using a working reference, minimal hypothesis testing, and one-at-a-time implementation.
  • Targeted mismatch scenarios: Covers disagreements in row counts, unique units, experiment metrics, sample ratios, timezones/window boundaries, join cardinality explosions, missing rows, hidden filters, and stale notebook state.

Quick Start

Use ds-systematic-debugging when your notebook and SQL disagree on treatment lift or row counts, and ask the agent to reproduce the mismatch and trace backward to the first transformation where values diverge.

Frequently Asked Questions about ds-systematic-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug metric discrepancies between SQL and notebook outputs?

To debug metric discrepancies, reproduce the mismatch and trace backward through joins, filters, and windowing to find where values first diverge. This evidence-first approach avoids speculative fixes by locating the exact broken transformation.

What causes sample ratio mismatch and experiment metric drift in data pipelines?

Sample ratio mismatch and metric drift stem from hidden filters, join cardinality explosions, or timezone windowing errors. Line-by-line pattern comparison against a known-working reference isolates the specific transformation causing the failure.

How do I trace missing rows and join cardinality errors in multi-step SQL pipelines?

Trace missing rows and join cardinality errors by reproducing the discrepancy and testing minimal hypotheses. Compare row counts and unique units line-by-line against a working reference to pinpoint the first broken transformation without speculative patches.

What is the best way to resolve stale notebook state conflicts with warehouse SQL results?

The best way to resolve stale notebook state conflicts is a phase-based root-cause investigation that validates evidence before applying one fix per rerun. This disciplined workflow traces mismatches backward to the first broken transformation.

Does systematic debugging work for timezone and window boundary errors in CTE pipelines?

Yes, systematic debugging works for timezone and window boundary errors by enforcing evidence-based validation across multi-step CTE pipelines. It reproduces the mismatch and traces backward through windowing logic to identify where unit alignment fails.