sql-to-business-logic
SQL to Business Logic Translator
When to use
- A stakeholder asks "what exactly does this query calculate?"
- Documenting a query library or a dbt model for non-technical readers
- Reviewing a query for correctness by comparing its logic to the business requirement
- Onboarding new analysts to existing SQL patterns
- Translating legacy undocumented queries before refactoring
Process
- Receive the query and context — obtain the SQL and the business question it answers. Also collect any schema notes (what the key tables and columns represent in business terms).
- Translate the FROM/JOIN structure — describe in plain language which data sources are combined and what type of join is used (inner keeps only matches; left keeps all rows from the left side). Note if the join type seems inconsistent with the stated purpose.
- Translate WHERE filters — list each filter condition as a business rule in plain language (e.g.,
status = 'completed'→ "only includes orders that have been paid and fulfilled"). - Explain GROUP BY and aggregations — describe what each aggregation computes and at what grain. Use
scripts/sql_explainer.pyto automate a first-pass structural parse. - Summarise output columns — for each output column, state its business meaning and any edge cases (nulls, rounding, currency units).
- Flag issues and write validation questions — identify potential problems (implicit null propagation, unexpected fan-out, hardcoded dates). Generate 3–5 questions the query author should confirm. Use
assets/query_documentation_template.mdto record the full translation.
Inputs the skill needs
- The complete SQL query (SELECT through ORDER BY)
- The business question the query is intended to answer
- Table and column descriptions (or a data catalog entry)
- Any business rules for key status values, date handling, or currency
- The intended output: who reads the result and for what decision
Output
scripts/sql_explainer.py— parses a SQL query and generates a structured plain-language explanationassets/query_documentation_template.md— completed translation covering purpose, step-by-step logic, output columns, business rules, and validation questions- Optionally: a flowchart representation of the query logic
More from nimrodfisher/data-analytics-skills
funnel-analysis
Conversion funnel analysis with drop-off investigation. Use when analyzing multi-step processes, identifying conversion bottlenecks, comparing segments through a funnel, or optimizing user journeys.
37metric-reconciliation
Cross-source metric validation and discrepancy investigation. Use when metrics from different sources don't match, investigating data quality issues between systems, or validating data migration accuracy.
31insight-synthesis
Transform data findings into compelling insights. Use when converting analysis results into actionable insights, connecting findings to business impact, or preparing insights for stakeholder communication.
31dashboard-specification
Design specifications for effective dashboards. Use when planning new dashboards, improving existing ones, or documenting dashboard requirements before development starts.
30data-quality-audit
Comprehensive data quality assessment against business rules, schema constraints, and freshness expectations. Activate when validating data pipeline outputs before production use, auditing a dataset against defined business rules, or producing a quality scorecard for a data asset.
30time-series-analysis
Temporal pattern detection and forecasting. Use when analyzing trends over time, detecting seasonality, identifying anomalies in time series, or building simple forecasting models for planning.
30