name: sql-data-gotcha-pack description: "Machine-readable gotcha rules for SQL and data engineering failure patterns. Loaded by data and SQL skills to enforce Never-do-X constraints grounded in real reporting failures." version: "1.0.0"

SQL and Data Gotcha Pack

This is a shared rule library. It is not a standalone skill. Data and SQL skills load it to enforce a common set of Never-do-X constraints.

How it works

Every rule in this pack has:

• A unique ID (G001 through G015)
• A severity: HIGH, MEDIUM, or LOW
• A machine-readable failure pattern used by CI
• A rationale grounded in a real reporting failure class
• A bad and good example
• A skill scope list (which skills enforce which rules)

Rules with failure_pattern_type: regex or regex_flag_only are caught automatically by sql_data_gotcha.flag_gotchas(text, skill).

Rules with failure_pattern_type: behavioral are injected as enforcement instructions into the dependent skill's SKILL.md and enforced by the LLM at generation time.

Rule Index

Enforcement model

For LLM skills

Dependent skills include this block in their Runtime Configuration:

gotcha_pack: "sql-data-gotcha-pack"
gotcha_pack_version: "1.0.0"
gotcha_enforcement: "block_on_high"

And a Gotcha Enforcement section that lists the applicable rule IDs and instructs Claude to check each before finalizing output.

For CI

from shared.sql_data_gotcha_pack.sql_data_gotcha import flag_report

result = flag_report(generated_sql, skill="sql-report-builder")
assert result["pass"], f"HIGH gotcha violations: {result['hits']}"

Adding rules

1. Add an entry to gotchas.json with the next sequential ID.
2. Add the skill to the skills list of each affected rule.
3. Add the rule ID to the Gotcha Enforcement block in each affected SKILL.md.
4. Add a test case to tests/shared/test_sql_data_gotcha_pack.py.
5. Run python tools/check_gotcha_coverage.py to verify all skills are covered.