mcpField
S
sql-to-business-logic

sql-to-business-logic

github.com/nimrodfisherData & databases504224 installsUpdated 5w ago
Repository

About sql-to-business-logic

A data-analysis skill for explaining SQL queries in business terms. It combines a structural parse with schema and business context to document logic, outputs, and validation questions.

Key features

  1. 01Plain-language explanation of query structure
  2. 02Translation of filters into business rules
  3. 03Aggregation and output-column explanations
  4. 04Potential issue and validation-question checks
  5. 05SQL parsing script and documentation template

Use cases

  1. 01Explain a query to non-technical stakeholders
  2. 02Document SQL libraries or dbt models
  3. 03Review query logic against business requirements
  4. 04Prepare undocumented SQL for refactoring

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nimrodfisher/data-analytics-skills --skill sql-to-business-logic

After installing, type/sql-to-business-logicin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

assets/
query_documentation_template.md
references/
sql_pattern_library.md
scripts/
sql_explainer.py

Details

From the project README

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

  1. 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).
  2. 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.
  3. 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").
  4. Explain GROUP BY and aggregations — describe what each aggregation computes and at what grain. Use scripts/sql_explainer.py to automate a first-pass structural parse.
  5. Summarise output columns — for each output column, state its business meaning and any edge cases (nulls, rounding, currency units).
  6. 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.md to 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 explanation
  • assets/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

Comments

Markdown supported