# Explain

> 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.

- Skill: `hainrixz/explain` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hainrixz/explain`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hainrixz/explain/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Hainrixz (https://skillmd.com/u/hainrixz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hainrixz/explain

---


# /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.
4. 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.
5. 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.