query-validation

name	query-validation
description	SQL query review for correctness, performance, and best practices. Activate when a query needs review before production use, shows unexpected results, or runs too slowly.

When to use

• A SQL query is about to be promoted to a production dashboard or report
• A query is returning surprising or incorrect results
• A query is running slowly and needs performance review
• You want to catch anti-patterns (implicit conversions, SELECT *, unbounded CTEs) before they cause incidents

Process

1. Lint the query — run scripts/sql_lint.py (sqlglot-based) to catch syntax errors, unsupported functions for the target engine, and style violations. Fix hard errors before continuing.
2. Review anti-patterns — compare the query structure against references/sql_anti_patterns.md. Flag any present anti-patterns with a severity rating.
3. Parse the explain plan — if an EXPLAIN or query profile output is available, run scripts/explain_plan_parser.py to extract slow steps (full table scans, missing indexes, high row estimates).
4. Estimate cardinality — run scripts/cardinality_estimator.py if schema stats are available to flag joins that might fan-out unexpectedly.
5. Check engine-specific behaviour — consult references/engine_specific_guide.md for the target engine (Snowflake / BigQuery / Postgres / Redshift) to verify date functions, window behaviour, and clustering assumptions.
6. Produce review output — fill in assets/query_review_template.md with findings; for any performance issues found, complete assets/optimization_recommendations.md.

Inputs the skill needs

• Required: the SQL query text
• Required: target database engine (Snowflake / BigQuery / Postgres / Redshift / other)
• Optional: relevant table schemas (column names, types, approximate row counts)
• Optional: EXPLAIN / query profile output
• Optional: expected business logic — what should the query calculate?

Output

• assets/query_review_template.md (filled) — categorised findings: correctness, performance, style
• assets/optimization_recommendations.md (filled, if issues found) — ranked rewrite suggestions with expected impact