Reviewing Data Model

reviewing-data-model — SKILL.md

> Variant: standard · When to use: judging a finished data-model document as an acceptance gate — checking an engineer can build the schema and write correct queries from it, then emitting VERDICT: approve|revise with actionable findings. Greenfield, or an amend (delta-scoped).

Overview

This skill is the review half of a producing/judging data-model pair. Loaded by a reviewer who holds a finished data-model document — the persistence/domain model an engineer implements the schema from and everyone who queries the data reads — it judges that doc against one question: can an engineer create the schema and write correct queries from it, and are the model's integrity rules + tradeoffs explicit? It applies a fixed 9-condition integrity + queryability checklist — the same bar a data-model author produces to (authoring-data-model's ## Output), so the produce-bar and the review-bar do not drift — then emits a single machine-parseable verdict plus findings the author can act on in one revision pass. It is an acceptance gate — it does not author, fix, or rewrite the model; it judges and returns findings, and the producer revises.

The bar is single-sourced with the author. The author's techniques — the ER notation (Chen / crow's-foot / Mermaid), the conceptual/logical/physical level framing, the normal-form-derivation procedure — are aids the reviewer judges by OUTCOME (is every entity typed + keyed? does every relationship carry cardinality + a referential rule? does every index trace to an access pattern?), never conditions to demand. But note the boundary: the access-pattern-justified-index discipline (cond-3), referential integrity (cond-2), and the normalization + paradigm reasoning (cond-4) ARE real, load-bearing conditions for a data model — this IS the persistence design, so do NOT under-review them as "implementation detail." What stays an aid is the technique (a named notation/level/derivation), not the outcome (a typed entity, a justified index, a stated tradeoff).

Paradigm-aware (load-bearing). The model may be relational, document/NoSQL, graph, wide-column, or key-value. Judge each in its own idiom: a NoSQL/graph/wide-column model legitimately has no normal form and no FK (it uses embed-vs-reference / edges / a partition+clustering key). Demanding a relational idiom of a non-relational model is the cardinal relational-reflex false-revise — do not do it.

When to activate

• A finished data-model doc needs an accept/revise decision before an engineer builds the schema.
• You are the independent reviewer / gate for a data model a producer just authored.
• Re-judging a revised data model after a prior revise verdict.
• Reviewing an amend — an approved model + a change request — as a delta-scoped review (cond-9).

Do NOT activate when:

• Authoring or repairing a data model → use authoring-data-model. This skill never writes the model.
• Reviewing the api-spec (the wire contract) or the feature-spec (what the features do) → those are their own documents with their own gates. The api-spec is a downstream consumer that references this model's entities — never an input here.
• Reviewing the persistence implementation (ORM/repository) or the executable DDL/migration code → this gate judges the design document, not code.
• Reviewing a generic / ad-hoc engineering design doc, RFC, ADR, spec, or plan → use design-review. This gate is for the doc-library data-model artifact — identified authoritatively by the template: data-model frontmatter; a # Data Model heading is a fallback signal only when frontmatter is absent.
• Checking template/section conformance → that is a template concern. This skill judges quality against the bar, not whether every heading is present.

Workflow

Step 1: Read the whole model with fresh, independent eyes

Read the data-model doc end to end as if encountering it for the first time. Your stance is a gatekeeper for the next step (an engineer building + querying the schema): a finding carries weight only when it shows the schema cannot be built or queried as designed. Keep the upstream feature-spec (+ architecture-doc store choice) at hand where given — cond-1/cond-8 check the model against the domain. Detect the paradigm(s) first (relational / document / graph / wide-column / key-value, possibly polyglot) so you judge each in its own idiom. The input is the doc itself — the access-pattern list lives in it (a template section); no separate companion artifact is required. Is this an amend? If you were handed a change request / delta against an existing model, run the delta-scoped path (cond-9 active; scope to the changed entities + their migration + ripple). On a greenfield first build no change request is present — cond-9 is n/a.

Step 2: Run the integrity + queryability checklist — judge each condition

For each condition, decide pass or gap. A condition fails only on a real, named deficiency — "I'd have modeled it differently" is not a gap. The conditions are the single-sourced bar; do not add private ones.

The capability-boundary checklist item (below) applies ONLY when a capability_record was injected into the authoring invocation and is available as review context. When absent, treat it as n/a — do not penalise a document for lacking capability-boundary markers when no boundary was defined.

1. Entities & attributes. Every entity has typed attributes + a key (primary, or partition+sort for NoSQL); the modeled shape is the stored shape, not the api-spec's wire DTO; entities trace to the feature-spec's domain. Gap on an untyped attribute, a keyless entity, a DTO modeled as if persisted (computed/flattened fields stored), or an entity serving no domain need. (Non-collapsing baseline — every entity is typed + keyed at any size.)
2. Relationships & referential integrity. Every relationship states cardinality; an M:N is realized by a junction entity (relational/document; a graph uses an edge); the FK/reference + owning side named; the on-delete rule stated (relational) or embed-vs-reference + the consistency-without-FK strategy stated (NoSQL/other). Gap on a relationship with no cardinality, a bare M:N line (no junction), a missing on-delete rule (relational), or an unbounded embed / FK-less reference with no consistency strategy (NoSQL). (Collapse: a one-entity store has no relationships. Non-collapsing where a relationship exists: it carries cardinality + a referential rule/strategy.)
3. Keys, constraints & access-pattern-justified indexes. A PK per entity (natural-vs-surrogate stated); uniqueness + check/cross-field constraints explicit; the access patterns enumerated; every index traces to an access pattern (no unjustified index, no missing-but-needed one). Gap on an index with no justifying query, a frequent query with no supporting index, an unstated key choice, or a business-uniqueness rule left unmodeled. (The signature condition. Collapse: a tiny store may need no secondary index — but the access patterns are still enumerated, and any index present is justified.)
4. Normalization & storage paradigm. The normal form (relational) or embedding/single-table strategy (NoSQL/other) stated; the paradigm chosen with rationale; each deliberate denormalization records its read-pattern + tradeoff + consistency strategy. Gap on unexplained redundancy causing update anomalies, a denormalized copy with no consistency strategy, an unstated/unjustified store choice, or a paradigm-mismatched model. (Paradigm-aware: a NoSQL/graph/wide-column model has no normal form — judge its embedding/edge/partition strategy instead; never revise it for "not being normalized.")
5. Data lifecycle & migration. Retention/archival + soft-vs-hard delete where needed; derived data names its source-of-truth + freshness; temporal/audit where history matters; a migration & seeding plan (expand-and-contract for a breaking change; backward/forward compatibility where rolling deploys apply). Gap on an unbounded-growth entity with no retention, a stored aggregate with no freshness mechanism, an implied in-place rename/drop on a populated table, or no plan to get from empty to running. (Collapse: a thin/first-draft model has a trivial lifecycle — light is fine.)
6. Diagram ⇄ catalog ⇄ tables in sync. Every entity/relationship in the Mermaid erDiagram appears in the entity catalog + the relationship/index lists and vice-versa; no orphan/drift. Gap on an element present in one rendering but missing from another. (Collapse: a one-entity model has a trivial diagram.)
7. Cross-cutting data quality. Sensitive attributes classified (PII/sensitive) + retention/residency where the data warrants; at-rest security for secrets (no plaintext credentials); the model viable at the target scale (no hot partition / unindexed hot query / unbounded row) — addressed where the data warrants. Gap on plaintext secrets, PII stored with no classification/retention where the domain clearly handles personal data, or a design that collapses at the stated scale. (Collapse: no PII → no classification; bounded data → light scale treatment.)
8. Grounded, honest & consistent. Entities/attributes reflect the feature-spec (not invented/boilerplate); assumptions explicit (thin-input → a blocker, not an invented schema); no fabrication; one-directional vs the api-spec (derived from the feature-spec, the api-spec only a downstream consumer — not reverse-engineered from DTOs); consistent with the shipped schema where one exists (claims about what IS stored verified against the real schema/migrations, file:line, marked unverified where unconfirmable). Gap on an invented entity/constraint/index, the api-spec-inversion, or a documented table/column/index that contradicts the real schema. (Non-collapsing baselines — no-fabrication + one-directional hold at any size. Greenfield clause: a brand-new/proposed/fictional model has no shipped schema to verify against → the consistency check is N/A, never a false-revise.)
9. (Amend only) delta is well-scoped, classified, ripple-clean, versioned. When reviewing a change against an existing model: the changed entities meet conditions 1–8 on what they touched; the change is classified additive/breaking with a migration plan (expand-and-contract for breaking) + a backward/forward compatibility analysis; the forward/downward ripple is flagged (the api-spec resources mapping onto changed entities, the impl/test-plan/runbook); the doc version bumped + a changelog present; superseded entities/attributes/indexes marked, not silently deleted. Gap on an un-scoped delta, a breaking change mis-classified as additive, an in-place rename/drop with no expand-contract plan, an un-flagged ripple, or a silent deletion. (Collapse: on a greenfield first build this condition is n/a — do NOT full-re-review an unchanged model, and do NOT demand a changelog on a first draft.)

1. Capability boundary (n/a when no capability_record): all owns entities have a primary table/collection; all refs entities are reference-only (FK only, no data duplication); publishes events have an outbox or event entry.

Proportionality. "Buildable + queryable" scales with the store. A thin store legitimately collapses what it does not need — one entity → no relationships; no M:N → no junction; nothing denormalized → no consistency strategy; no history requirement → no temporal model; first draft → no migration/changelog; no PII → no classification. Judge completeness of the integrity + queryability decisions, not word count or template-section presence. A small, complete model that satisfies every applicable condition passes. Do not manufacture a gap from brevity.

Step 3: Decide the verdict

• approve — every applicable condition passes. An engineer can build the schema and write correct queries from it without asking the author; the integrity rules + tradeoffs are explicit. Approve even if you can imagine stylistic improvements; the bar is buildability + queryability, not perfection.
• revise — one or more conditions have a real, named gap that blocks building or querying (an untyped attribute, a relationship with no on-delete rule, an unjustified or missing index, a denormalized copy with no consistency strategy, a DTO-inversion, an in-place breaking migration, an un-scoped amend, etc.).

Do not revise to signal effort or to request nice-to-haves. A condition is either met or it isn't.

Step 4: Emit the verdict + actionable findings

Emit the verdict as a single line — the literal text VERDICT: approve or VERDICT: revise, on its own line, with no surrounding code fences, quotes, or extra words (the fences here are illustration only):

VERDICT: approve

Then, on the following lines, list findings. On revise, every finding is actionable — the failed condition, the exact location, and how to fix it — so the author can resolve it in one pass. On approve, findings are optional non-blocking notes.

A good finding names the gap and the fix:

> revise — Relationships & referential integrity (cond. 2), §3: the Order→Customer relationship shows a line but no on-delete rule. Fix: state ON DELETE RESTRICT (you cannot delete a customer with existing orders), so the integrity semantics are not left for the engineer to invent.

A bad finding is vague and unactionable:

> The relationships section could be tightened up. (Which relationship? Why does it fail the bar? What fixes it?)

Rules

Hard rules (never violate):

• Emit exactly one verdict line, VERDICT: approve or VERDICT: revise — that literal token, on its own line, nothing else on it. Downstream tooling parses it.
• Judge, never author. Return findings; do not rewrite, fix, or fill in the model. The producer revises.
• Single-sourced bar. Judge against the ten conditions in Step 2 — the same bar the author (authoring-data-model's ## Output) produces to. Do not invent extra conditions or apply a stricter private standard.
• Aids are judged by outcome, never demanded. The ER notation, the conceptual/logical/physical levels, the normal-form-derivation procedure are the author's techniques — judge whether the entity is typed / the relationship carries a referential rule / the index is justified, NEVER "you didn't use crow's-foot / draw a conceptual model / show the FD derivation." (Access-pattern-indexes / referential-integrity / normalization OUTCOMES are real conditions cond-2/3/4 — only the techniques are aids.)
• Paradigm-aware — no relational reflex. Never revise a NoSQL/graph/wide-column model for lacking a normal form or an FK; judge its embed-vs-reference / edge / partition strategy instead. This is the cardinal drift this gate guards against.
• No false-revise. A model that meets every applicable condition is approved, even a thin one for a small store. Revise only on a real, named gap. A thin store legitimately omits relationships, denormalization, temporal history, a migration, a changelog.
• No false-approve. Never approve over a genuine gap to be agreeable. A blocking gap is a revise.
• Every index traces to an access pattern (cond. 3). An unjustified index is a real gap (write-amplification + storage), not a style nit; a missing index for a hot query is a real gap.
• Judge against the upstreams the document was given. Assess the model against its depends_on set + the docs it references. A not-produced / not-handed-in upstream (e.g. an absent feature-spec) is never a revise trigger. A model that ignored a produced upstream it should have traced to is a fair finding.
• Amend is delta-scoped. When handed a change ag

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bm629
• Source: bm629/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.