feat(dsql): enhance query plan explainability with type coercion detection, rewrites, and workflow extraction

[Morlej]

Summary

• Extract Workflow 8 from SKILL.md into references/query-plan/workflow.md (SKILL.md: 334 → 281 LOC)
• Add type coercion index bypass detection — pg_amop-based detection in plan-interpretation.md, indexed column type queries in catalog-queries.md
• Add query rewrite references — 11 generic patterns split into individual files under query-rewrites/, plus 2 DSQL-specific rewrites (reltuples estimate, split large joins)
• Add structured trigger criteria, context disambiguation, and routing to the workflow reference
• Wire rewrites into workflow — loaded at Phase 0, applied at Phase 2

Validation

• validate-size.py: 281 lines (good, under 300 limit)
• validate-references.py: 0 broken links, 0 new orphans

Eval Results

Manual qualitative comparison (n=1, Claude Opus 4.6). Full results in tools/evals/databases-on-aws/dsql/query_plan_rewrite_eval_results.md:

Eval	Scenario	With Skill	Baseline	Key Delta
200	IN-subquery Full Scan	PASS	PARTIAL	Skill recommends specific rewrite patterns from reference
201	Type coercion index bypass	PASS	PASS	Both identify it; skill adds DSQL-specific pg_amop detail
202	12-table join ordering	PASS	PARTIAL	Skill offers full diagnostic workflow with GUC experiments
203	COUNT(*) timeout	PASS	FAIL	Skill recommends pg_class reltuples with staleness warning
204	Multiple OR to IN	PASS	PARTIAL	Skill identifies pattern from reference
205	GROUP BY after JOIN	PASS	PARTIAL	Skill recommends subquery aggregation
206–210	LEFT JOIN, computation push, NOT IN+NULL, UNION ALL, negative	Added in review round	—	Coverage for remaining patterns + negative case

Follow-ups

• MCP mirror PR: awslabs/mcp src/aurora-dsql-mcp-server/skills/dsql-skill/ needs to be synced with these changes (workflow.md, query-rewrites/ split, updated catalog-queries.md, plan-interpretation.md). Will open companion PR after this merges.
• Python SQL converter: Per review feedback, deterministic rewrites should migrate to a Python script in a future PR (reference files then document the converter's rules).

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

🤖 Generated with Claude Code

[amaksimo]

I have a few general commets:

1. We should use positive language throughout (llm can confuse DO with DO NOT when we trim context)
2. We should try to use RFC language more frequently throughout
3. We should break up the references in the query-plan folder as some of the files are very long

[anwesham-lab]

why did we end up adding line breaks?

[anwesham-lab]

why remove the bullet structure?

[anwesham-lab]

is this an always? contextualize when/how often? Should this be an SHOULD Skip when?

[anwesham-lab]

is this a should or a must? should gives the model a directive to bypass when told something like to rush

[anwesham-lab]

since so many of these are deterministic, I question the meta structure of if we should instead leverage something like a python script converter of sorts that can parse and replace the SQL and the reference files just execute them?

[anwesham-lab]

PR #162 — Review Summary

feat(dsql): enhance query plan explainability with type coercion detection, rewrites, and workflow extraction

Reviewed at head SHA 07b6baaca029e3336ddfb03438eee26429734a72. Sound direction; eval gains are real (especially eval 203 reltuples). Holding on five correctness bugs in the new SQL example pairs (rows 1–5) — agents will copy these into production rewrites that change result sets — plus a dangling cross-reference cluster (rows 6–8) where workflow.md, plan-interpretation.md, and catalog-queries.md reference an "implicit cast compatibility matrix" and a "Phase 5" that no longer exist after the rewrite. Structural, eval, and process items follow.

#	Confidence	Area	Finding	Suggestion	Reviewed SHA
1	95	query-rewrites/push-computation-to-constant.md L9-17 — correctness	First example is not equivalent under integer division. Original WHERE emp_no * 100 / 5 = 10001 has no integer solution; rewrite WHERE emp_no = 10001 * 5 / 100 matches emp_no = 500. The file's own "Skip when … integer-division rounding" caveat is violated by the leading example.	Replace with a genuinely invertible example (e.g. emp_no + 100 = 10001 → emp_no = 9901), or use a numeric/float column.	07b6baa
2	90	query-rewrites/not-in-to-not-exists.md L1-26 — correctness	"Sidesteps NULL semantics issues" understates: when the subquery contains NULL, NOT IN returns empty and NOT EXISTS returns the rows; the rewrite changes results, not just performance.	State explicitly: "NOT EXISTS does not preserve NOT IN's NULL-propagation; output differs when the subquery may contain NULLs. Confirm intent with the user before applying."	07b6baa
3	85	query-rewrites/subquery-unnesting-uncorrelated.md L9-23 — correctness	SELECT DISTINCT R.* collapses pre-existing duplicates in R that the original semi-join (IN (SELECT …)) preserved — fixes one duplicate problem by introducing another.	Either (a) recommend the EXISTS form (true semi-join) or (b) state the assumption "Apply only when S.b is unique (PK/UNIQUE); otherwise DISTINCT changes results."	07b6baa
4	85	query-rewrites/subquery-unnesting-correlated.md L20-26 — correctness	Same DISTINCT-on-semi-join issue as #3 for the EXISTS→JOIN rewrite.	Same fix: prefer EXISTS, or document the uniqueness precondition.	07b6baa
5	85	query-rewrites/subquery-unnesting-scalar.md L33-52 — correctness	s_count example: scalar COUNT(*) returns 0 for outer rows with no match; LEFT JOIN+GROUP BY rewrite returns NULL. Downstream WHERE s_count = 0, SUM(s_count), etc. break silently. The first MAX example is fine (MAX returns NULL on empty).	Wrap with COALESCE(Agg.s_count, 0) AS s_count; add a one-line note that COUNT/SUM need COALESCE while MAX/MIN do not.	07b6baa
6	95	workflow.md L29-31 — correctness	Trigger row references "Phase 5 re-entry for an existing report" but the workflow defines only Phase 0–4 (TOC L7–14). Routing L56 correctly says "append Addendum".	Replace with "Reassessment re-entry — re-runs Phase 1–2 and appends an Addendum per Phase 4."	07b6baa
7	90	plan-interpretation.md L194-242, workflow.md L100, catalog-queries.md L122-124 — correctness	Three files reference an "implicit cast compatibility matrix below/above/in plan-interpretation.md" that does not exist. The section was rewritten to recommend a live pg_amop query instead. Eval 201's expectation "Mentions implicit cast compatibility matrix" reinforces the phantom artifact.	Replace all four references with "the pg_amop query in catalog-queries.md (B-Tree Cross-Type Operator Support)." Update eval 201 expectation accordingly.	07b6baa
8	80	plan-interpretation.md L201-214 — correctness	Bullet at L202 says "if an implicit cast exists, the planner can still use the index" — contradicts L211–214 which correctly notes B-Tree needs a registered cross-type operator (pg_amop), not just a pg_cast. The two paragraphs disagree.	Drop or rephrase L202: "If a cross-type B-Tree operator is registered (see pg_amop), the index can be used; otherwise the planner applies a per-row cast that defeats index ordering."	07b6baa
9	75	plan-interpretation.md L214 — correctness/durability	"Cross-type index support is limited to the integer family" stated as fact, no citation, no "verify before asserting" hedge. Will rot the moment DSQL adds a cross-type operator family.	Prefix with "At time of writing…" and route the agent through the pg_amop query before asserting this to a user.	07b6baa
10	70	catalog-queries.md L136 — correctness	amopmethod = 10003 is a DSQL-internal magic number (PG mainline B-Tree is 403). No provenance comment; will silently break if the OID changes.	Add inline comment explaining provenance and a SELECT oid FROM pg_am WHERE amname = 'btree' recommendation as a hedge.	07b6baa
11	90	catalog-queries.md TOC L5-13 — structure	TOC omits 3 of the 9 sections — all PR additions: "Column Types for Predicate Columns" (L107), "B-Tree Cross-Type Operator Support" (L125), "Indexed Column Types" (L157).	Add three TOC entries between current items 5 and 6.	07b6baa
12	90	plan-interpretation.md TOC L3-14 — structure	TOC omits "Type Coercion and Index Bypass" (L186) — the headline new section of this PR.	Insert TOC entry, renumber subsequent items.	07b6baa
13	80	SKILL.md L112-115 — structure	The PR rewrites this block but uses a single combined When:/Contains: while sibling "(modular):" sections give each sub-file its own #### heading + per-file When/Contains. Loading conditions for plan-interpretation.md, catalog-queries.md, guc-experiments.md, report-format.md, and the rewrite indexes are no longer declared in the entry file.	Either give each query-plan reference its own #### entry, or explicitly delegate routing to workflow.md and state that as the rule.	07b6baa
14	80	tools/evals/databases-on-aws/README.md — multi-target sync	New query_plan_rewrite_evals.json is not added to the README's directory tree or per-tier eval section. Sibling evals (evals.json, query_explainability_evals.json) all have entries. The cluster-fixtures table also misses the new schemas (12-table join, 50M-row table).	Add the new eval and a fixtures row to the README.	07b6baa
15	75	tools/evals/databases-on-aws/dsql/scripts/ — process	New eval JSON has no paired runner script under scripts/. Sibling evals all have one. PR ships only manual query_plan_rewrite_eval_results.md.	Either add run_query_plan_rewrite_evals.py (LLM-judge fits) or document explicitly that this suite is manual-only.	07b6baa
16	70	query_plan_rewrite_evals.json — tests	Coverage gap: 5 of 11 generic rewrites have no direct eval — left-join-to-inner, propagate-filter, push-computation-to-constant, not-in-to-not-exists, flatten-union-all. NOT IN→NOT EXISTS especially worth covering (correctness, not just perf). No negative cases (where the agent should decline the rewrite).	Add evals 206–212 covering missing patterns + at least one "OR across different columns → does NOT recommend OR-to-IN" negative case.	07b6baa
17	65	query_plan_rewrite_eval_results.md — tests	Sample size = 1 per cell, no model/version/temperature recorded, no variance analysis. PASS/FAIL is a single human transcript read.	Record model + version + n=3 with majority vote; add a Runs column; or downgrade the table to "qualitative comparison."	07b6baa
18	75	PR description — pr-body	PR body / commit 82617135 claim "275 lines (good)" but SKILL.md is 279 lines at head. Still under cap; cosmetic but it's a stated correctness claim.	Re-run validate-size.py on 07b6baa and update the PR body / commit message.	07b6baa
19	65	Multi-target sync (awslabs/mcp) — process	awslabs/mcp@main src/aurora-dsql-mcp-server/skills/dsql-skill/references/query-plan/ does NOT contain workflow.md, query-rewrites/, or the new index files. PR description does not mention an MCP-mirror PR or follow-up. Per the dsql-skill-author placement rules, the default DSQL skill must propagate to the MCP standalone skill + Kiro Power.	Open a companion PR against awslabs/mcp mirroring the new files (and translate workflow.md for Kiro Power), or document explicitly that the mirror is out of scope and link the follow-up issue.	07b6baa
20	70	SKILL.md L172-173, L266-267 — silent-failure	This PR softens the awsknowledge fallback rule from "flag that" to "note to the user that" — advisory phrasing, not a MUST. Agent can silently use stale defaults for decisions that turn on the exact value.	Promote to MUST: "MUST tell the user the lookup failed, MUST name the limit and value, MUST refuse the fallback when the recommendation depends on the exact value."	07b6baa
21	70	query-rewrites/reltuples-estimate.md + eval 203 — silent-failure	reltuples reflects last ANALYZE/autovacuum and may be drastically stale on a fresh or write-heavy table. Doc says "estimate, not exact" but does not require warning the user about staleness; eval 203 lacks the staleness expectation, so the failure mode is unobservable.	Add MUST: "Warn the user that reltuples reflects the last ANALYZE; recommend cross-checking last_analyze when the count drives a decision." Add eval expectation.	07b6baa
22	70	catalog-queries.md L107-180 (PR-added sections) — security	The 3 new sections this PR adds (Column Types for Predicate Columns, B-Tree Cross-Type Operator Support, Indexed Column Types) introduce fresh '{schema}' / '{table}' placeholder substitution patterns. SKILL.md Workflow 4 mandates safe_query.build() for query construction; these new examples teach lexical concatenation, an injection sink despite readonly_query.	Add a one-line MUST scoped to the new sections: "Substitute these placeholders via safe_query.build() with ident() — see input-validation.md."	07b6baa
23	60	query-rewrites/*.md (all 13) — style	Every new rewrite file pairs **SHOULD apply when:** with **Skip when:**. The two are logical complements; per authoring-style.md §Voice reserve prohibition for irreversible harm.	Drop Skip when: and tighten SHOULD apply when:, or rephrase as a single **Applies when:** criterion.	07b6baa
24	80	workflow.md TOC L7-15 — structure	TOC anchors encode the em dash with double hyphens (e.g., #phase-0--load-reference-material). GitHub collapses — to a single -, so all five Phase TOC links are broken in the rendered file.	Regenerate as #phase-0-load-reference-material … #phase-4-produce-the-report-invite-reassessment (and #phase-3-experiment-conditional).	07b6baa

Reviewer scope. This review covered the diff at the head SHA (21 files, +1131 / −36) — the new query-plan workflow extraction, type-coercion detection, 11-pattern rewrite library, and eval pair. Prior amaksimo review threads from the predecessor PR #161 (file split, RFC keywords, positive language, DATEADD→NOW()-INTERVAL, psql fallback removal) are addressed at this head; thank you.

---

🤖 This review was drafted with Claude Code using the dsql-skill-author Workflow 2 (reviewer) procedure and the 17+ sub-agent roster from code-review.md. Findings have been validated through the five-gate filter (re-read at head SHA, applicability, suggestion correctness, customer-value, confidence ≥ 60).

Was this review useful? React with 👍 if the findings were helpful, 👎 if they missed the mark or introduced false positives. Reply with specifics so the review process can improve. Findings you disagree with are valid to push back on — confidence scores are not verdicts.