# Reviewing Data Model > > - **Type:** Skill - **Install:** `agentstack add skill-bm629-agent-skills-reviewing-data-model` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [bm629](https://agentstack.voostack.com/s/bm629) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [bm629](https://github.com/bm629) - **Source:** https://github.com/bm629/agent-skills/tree/main/skills/reviewing-data-model ## Install ```sh agentstack add skill-bm629-agent-skills-reviewing-data-model ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # `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.)* 10. **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](https://github.com/bm629) - **Source:** [bm629/agent-skills](https://github.com/bm629/agent-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-bm629-agent-skills-reviewing-data-model - Seller: https://agentstack.voostack.com/s/bm629 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.