| name | explain |
| description | Explain a database schema, model, or a single finding in plain language, with a paradigm-aware diagram — what the tables/collections/keyspaces are, how they relate, and where the data lives. Read-only; teaches, does not change anything. Use when the user asks to explain, describe, walk through, draw, or diagram a schema, a data model, a relationship, or what a specific audit finding means. |
| argument-hint | <path|table|finding-id> | --query "<SQL>" | <paste an EXPLAIN plan> [--depth overview|detailed] [--lang en|es] |
| allowed-tools | Read, Grep, Glob, Bash |
/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
- Detect the paradigm/engine (
scripts/detect-stack.mjs) and parse the model (scripts/parse-schema.mjs / parse-orm-python.py).
- 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").
- 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.
- 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.
- 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.
