/claude-db:explain

Plain-language description of a schema (or one finding), plus a paradigm-aware diagram. Read-only — explains, never edits or migrates.

$ARGUMENTS = <path|table|finding-id> [flags]. The target can be a schema/ORM/migration path, a single table/collection name, or a finding id from a prior audit.

What to do

1. Detect the paradigm/engine (scripts/detect-stack.mjs) and parse the model (scripts/parse-schema.mjs / parse-orm-python.py).
2. Give a plain-language description first — no jargon in the opening: what each entity holds, who owns what, and how the pieces connect, in the user's words ("a user has many orders; each order belongs to exactly one user").
3. Render a paradigm-aware diagram (Mermaid) with node scripts/gen-diagram.mjs --file <schema> [--paradigm relational|document|key-value|wide-column|graph] — paradigm-aware: ERD for relational, access-pattern map for document, key+GSI sketch for DynamoDB/KV, node/edge for graph:

- Relational → erDiagram with tables, PKs/FKs, and cardinality. - Document → embedding/reference tree showing what is nested vs referenced. - Key-value → access-pattern / key-design sketch (partition + sort key). - Wide-column → table-per-query / partition-key layout. - Vector → collection + metric/dimension + metadata filter fields. - Time-series → hypertable / measurement + tags + retention. - Graph → node-and-edge sketch with relationship types.

1. Offer an expandable technical layer below the plain description: exact column types, index definitions, constraint names, on-delete behavior — for the reader who wants the precise DDL.
2. If the target is a finding id, explain what it checks, which score/axis it affects (design | performance | both), why it matters, and how to reproduce it (verification.reproduce).

Query / EXPLAIN-plan mode

Two additional inputs, both reusing the db-query-patterns (M13) reasoning:

• --query "<SQL>" — given a raw SQL statement, explain in plain language why it would be slow and what fixes it: detect M13 shapes (SELECT *, structural N+1, OFFSET deep paging, non-SARGable predicates), then recommend the concrete index, keyset rewrite, or predicate change that lets an index be used. This is static reasoning over the query text — no live DB needed.
• paste-an-EXPLAIN-plan — given a pasted EXPLAIN/EXPLAIN ANALYZE plan, read the plan nodes (seq scans, sort/hash spills, row estimate vs actual, nested-loop blowups) and explain which step dominates and what index/rewrite removes it, again via the M13 reasoning.
• If the user wants a live plan generated for them (running EXPLAIN against their database) rather than pasting one, mark the request needs_api / Tier-2 and do not fabricate plan numbers — explain statically from the query text instead, or ask them to paste the plan.

Honesty

• Describe only what is actually in the model. Never invent columns, relationships, row counts, or latency. If a relationship is implied but not enforced (e.g. a logical FK with no constraint), say so explicitly.
• Respond in the user's language (EN/ES); --lang overrides.