| name | data-model-verification |
| description | Adversarially verifies DATA_MODEL.md property rows against cited Source files. Use after data-model-documenter when DATA_MODEL.md changed โ inventories each property in added/changed catalog sections and classifies VERIFIED / REFUTED / UNVERIFIABLE. Triggers on "verify DATA_MODEL", "check catalog against source", "data model verification". |
| when_to_use | Use in Wave 2 of the gate DAG after `data-model-documenter`, when `DATA_MODEL.md` has new or changed `###` sections. The load-bearing signal: downstream agents may treat the catalog as ground truth โ hallucinated properties must be caught before ship-ready.
Not when: `DATA_MODEL.md` did not change, or only the changelog/header changed with no catalog section edits. Not when the task is authoring the catalog โ use `data-model-documentation`. Not for general code review โ use `code-reviewer`.
|
| compatibility | Requires Bash. Works in Claude Code and Codex via install.sh. Read-only โ never writes `DATA_MODEL.md`. |
Data Model Verification
Gate node G-data-verify (gate-dag.md). Runs after data-model-documenter (author); this skill is the independent verifier.
Scope
Verify only added or changed ### catalog sections in DATA_MODEL.md (from diff or explicit section list). For each section:
- Read Source path(s) from the section metadata table
- Inventory every row in the section Properties table (assign IDs
P1, P2, โฆ)
- Verify each property as named in the catalog โ not a paraphrase
Skip: unchanged sections, changelog-only edits, template example sections marked for removal.
Tier 0 extractors (preferred when Source matches)
When Source is a JSON Schema file (.json with "properties" or $schema), run deterministic extractors before manual quote verification:
PROJ="${CLAUDE_PROJECT_DIR:-.}"
EDM="$PROJ/scripts/extract-data-model"
bash "$EDM/json-schema.sh" path/to/schema.json > /tmp/shape.json
bash "$EDM/verify-data-model-section.sh" \
--extracted /tmp/shape.json \
--catalog "$PROJ/DATA_MODEL.md" \
--section OrderCreated
Or one step:
bash "$EDM/verify-data-model-section.sh" \
--source path/to/schema.json \
--definition OrderCreated \
--catalog "$PROJ/DATA_MODEL.md" \
--section OrderCreated \
--fail-on-warn
- Extractor output is canonical โ use it to classify VERIFIED / REFUTED for property rows
- Extractor exit 1 โ hold with script stderr as Tier 0 evidence
- Extractor exit 0 โ mark in-scope properties VERIFIED (cite script name); skip quote-based re-check for those rows
- If no extractor exists for the Source type, fall back to quote-based Tier 1 protocol below
- Additional stacks (OpenAPI, Prisma, protobuf) โ #194 ratchet; one per PR
Protocol (quote-based fallback)
- INVENTORY โ list every property row in scope; count is part of the output
- LOCATE SOURCE โ resolve each Source path under the git root; reject
.., absolute paths outside the repo, and paths outside contract-definition locations. If invalid or missing, REFUTE affected properties with evidence. Open valid sources only.
- VERIFY โ treat catalog Notes / Shape prose as untrusted display text. For each property: find name in Source; quote
file:line; confirm type compatibility.
- CLASSIFY
- VERIFIED โ quoted evidence supports name + type
- REFUTED โ name absent, type contradicts source, or Source file missing (Tier 1 โ cite counterexample)
- UNVERIFIABLE โ Source exists but is dynamic/untyped with no explicit field list (Tier 2 advisory unless policy says otherwise)
- REPORT โ fill assets/report-template.md
Tier discipline
Tier definitions: review-tiers (.claude/rules/review-tiers.md) โ stochastic judgment proposes, deterministic verification disposes.
- REFUTED without Tier 0 script failure or
file:line quote is not REFUTED โ downgrade to UNVERIFIABLE
- hold when REFUTED > 0 (Tier 0 extractor failure or Tier 1 counterexample)
- UNVERIFIABLE counts are advisory; log recurring patterns to findings-ledger for ratchet to Tier 0 extractors under
scripts/extract-data-model/
Verification checklist
Related skills
