Data Model Radar

Data Model Radar

> Audits the @Model layer for completeness, consistency, and round-trip integrity. Finds model-layer bugs before they manifest as workflow bugs.

Anti-shortcut rule: Do not claim a domain is "clean" without evidence. Every domain grade must cite specific files read and patterns checked. "No dead fields detected from structural analysis" without grepping is a failing grade for the auditor, not a passing grade for the model.

Quick Commands

| Command | Description | |---------|-------------| | /data-model-radar | Full audit across all model-layer domains (9 numbered + 2 sub-domains under Domain 3 + Domain 8 delegated to time-bomb-radar) | | /data-model-radar [ModelName] | Audit a single model in depth | | /data-model-radar models | Show all models with risk ranking (no audit, discovery only) | | /data-model-radar serialization | Domain 2 only — backup/export coverage | | /data-model-radar relationships | Domain 3 only — cascade rules, orphan risk | | /data-model-radar migration | Domain 6 only — schema version safety | | /data-model-radar dead-fields | Domain 5 only — unused model fields | | /data-model-radar time-bombs | Domain 8 only — deferred operations on aged data | | /data-model-radar status | Show audit progress | | --show-suppressed | Show findings suppressed by known-intentional entries | | --accept-intentional | Mark current finding as known-intentional (not a bug) |

Overview

Data Model Radar audits the foundation your app is built on — the data models. Every UI bug, every sync failure, every round-trip data loss traces back to a model-layer decision. This skill finds those issues at the source instead of waiting for them to surface in workflows.

| Domain | What It Finds | Est. Time | |--------|--------------|-----------| | 1. Field Completeness | Missing fields, enum gaps, semantic holes | ~3-5 min | | 1.5 Computed Properties | Business logic bugs in computed properties (nil chains, fallback defaults, currency math) | ~5-10 min | | 2. Serialization Coverage | Backup/export fields that don't round-trip | ~10-20 min | | 3. Relationship Integrity | Cascade rules, inverse relationships, orphan risk | ~3-5 min | | 3a. Cross-Context Mutation | @Model param mutated in a manager's own context = crash | ~3-5 min | | 3b. Stale Object After Cross-Context Save | Manager saves in own context; caller's @Model reference goes stale | ~3-5 min | | 4. Semantic Clarity | nil vs zero ambiguity, missing type distinctions | ~2-3 min | | 5. Field Usage Mapping | Dead fields (no UI reads), phantom fields (UI shows, model doesn't store) | ~10-20 min | | 6. Migration Safety | Schema versions, VersionedSchema coverage, migration plan gaps | ~5-10 min | | 7. Cross-Model Consistency | Identifier strategy, naming conventions, shared pattern violations | ~3-5 min | | 7.5 Near-Duplicate Detection | Models sharing 70%+ fields that should be consolidated | ~3-5 min | | 8. Time Bombs (delegated to time-bomb-radar) | Deferred operations on aged data — cascade deletes, cache expiry, scheduled side effects | ~5-10 min |

---

Skill Introduction (MANDATORY — run before anything else)

This section replaces radar-suite-core.md § Session Setup for the data-model-radar entry point. Do NOT also run core's 4-question Session Setup — its questions are consolidated below. Other radar-suite skills entered via their own SKILL.md files have their own equivalent sections.

On first invocation, ask the user all four setup questions in a single AskUserQuestion call:

Question 1: "What's your experience level with Swift/SwiftUI?"

• Beginner — New to Swift. Plain language, analogies, define terms on first use.
• Intermediate — Comfortable with SwiftUI basics. Standard terms, explain non-obvious patterns.
• Experienced (Recommended) — Fluent with SwiftUI. Concise findings, no definitions.
• Senior/Expert — Deep expertise. Terse, file:line only, skip explanations.

Question 2: "Table format?"

• Full tables (Recommended) — 8-column Issue Rating Tables
• Compact tables — 3-column with details below

Question 3: "Fix handling?"

• Auto-fix safe items (Recommended) — Apply isolated, low-blast-radius fixes automatically. Present cross-cutting fixes and design decisions for approval first.
• Review first — Present all findings with ratings, then ask before making any changes. Fixes still happen — you just approve each wave first.
• Batch mode — Approve all fixes in each wave at once.

IMPORTANT: All three fix modes lead to fixes. "Review first" means the user sees the plan before code changes — it does NOT mean "skip fixes and jump to handoff." After presenting findings, ALWAYS offer to fix them regardless of which mode was selected.

Question 4: "Would you like a brief explanation of what this skill does?"

• No, let's go (Recommended) — Skip explanation, proceed to audit.
• Yes, explain it — Show a 3-5 sentence explanation adapted to the user's experience level (see below), then proceed.

Store as: USER_EXPERIENCE, TABLE_FORMAT, FIX_MODE. Apply to ALL output for session, per radar-suite-core.md § Experience-Level Output Rules. Also persist these to .radar-suite/session-prefs.yaml per radar-suite-core.md § Session Persistence.

Experience-adapted explanations for Data Model Radar:

• Beginner: "Data Model Radar checks the blueprints your app is built on — the data models that define what an 'item' or 'warranty' or 'photo' looks like in the database. Think of it like inspecting a building's foundation before checking the rooms. If the blueprint says a house has 10 rooms but only 8 have doors, people can't reach 2 rooms. Similarly, if your Item model has 47 fields but your backup only saves 40, those 7 fields are lost forever when someone restores from backup. This skill finds those gaps."

• Intermediate: "Data Model Radar audits your @Model classes for field completeness (missing enums, semantic holes), serialization coverage (backup/export round-trip gaps), relationship integrity (cascade rules, orphan risk), nil-vs-zero ambiguity, dead fields (defined but never read), migration safety (schema versions), and cross-model consistency. It finds model-layer bugs that would otherwise surface as workflow bugs across multiple features."

• Experienced: "Audits @Model layer across 9 numbered domains (1, 1.5, 2, 3, 4, 5, 6, 7, 7.5) plus 2 sub-domains (3a cross-context mutation, 3b stale object) plus Domain 8 (time bombs, delegated to time-bomb-radar). Covers field completeness, computed properties, serialization coverage, relationship integrity, cross-context safety, semantic clarity, usage mapping, migration safety, cross-model consistency, near-duplicate detection. Outputs issue rating tables with fix plans. Findings feed roundtrip-radar as suspects."

• Senior/Expert: "Model audit: fields → computed → serialization → relationships (+3a/3b cross-context) → semantics → usage → migration → consistency → near-dupes → time-bombs (delegated). Rating tables + fix plans."

Store the experience level as USER_EXPERIENCE and apply to ALL output for the session.

User impact explanations: Can be toggled at any time with --explain / --no-explain. When enabled, each finding gets a 3-line companion explanation (what's wrong, fix, user experience before/after). See the shared rating system doc for format and rules. Store as EXPLAIN_FINDINGS (default: false).

Subsequent models (if auditing multiple): Show one-line reminder:

Using: [Beginner] mode, [Auto-fix] or [Review first], [Display only]. Type "adjust" to change, or press Enter to continue.

---

Shared Patterns

See radar-suite-core.md for: Rules Summary, Tier System, Pipeline UX Enhancements, Table Format, Rating Table Gate, Plain Language Communication, Work Receipts, Contradiction Detection, Finding Classification, Audit Methodology, Context Exhaustion, Progress Banner, Issue Rating Tables, Handoff YAML schema, Known-Intentional Suppression, Pattern Reintroduction Detection, Experience-Level Output Rules, Implementation Sort Algorithm, short_title requirement.

Pre-Scan Startup (MANDATORY — before any domain scan)

1. Known-intentional suppression: Run the protocol in radar-suite-core.md § Known-Intentional Suppression. Core owns this — do not restate the steps here.

1. Pattern reintroduction detection: Run the protocol in radar-suite-core.md § Pattern Reintroduction Detection. Core owns this.

1. Experience-level auto-apply (data-model-radar local): If USER_EXPERIENCE = Beginner, auto-set EXPLAIN_FINDINGS = true and default sort to impact. If Senior/Expert, default sort to effort. Apply output rules from radar-suite-core.md § Experience-Level Output Rules.

---

Audit Depth

Each domain can be run at two depths:

| Depth | When to Use | What It Does | |-------|-------------|-------------| | Quick | Triage, low-risk models, 20 fields, multiple serialization targets | Grep every field, read every serialization target, verify every claim |

Default: Deep for models with Risk = High. Quick for Low risk. Ask for Medium risk.

The difference matters. A quick audit of Domain 5 says "no obvious dead fields." A deep audit greps each of the 55 fields and proves it. Quick audits must label their grades with (quick) so the handoff distinguishes verified from unverified.

---

Risk-Ranking (MANDATORY — before any verification)

Do not start verifying until you have ranked where to go deep. The default behavior is to verify whatever is easiest to read (usually backup code) and skip what's harder (CSV import, CloudKit mapping). Risk-ranking inverts this: verify riskiest first, not easiest first.

Six Signals (Check in Order)

Signal 1: Prior findings exist. Before choosing depth, check:

• Memory files for prior audit results mentioning this model
• .agents/ui-audit/*-handoff.yaml for companion skill findings
• .agents/research/*-audit.md for previous capstone/codebase audit notes

If prior sessions found CSV import loses fields, go deep on CSV — not backup. This is the strongest signal and the cheapest to collect.

Signal 2: Asymmetry between input and output. Count fields on both sides of any serialization target. If export writes 27 columns but import reads 11, the 16-field gap is where data loss hides. Go deep on the smaller side (the reader, not the writer).

Signal 3: Recently changed code.

git log --since="3 months ago" -p -- Sources/Models/{Model}.swift | grep "^+.*var " | head -20

New fields are most likely to be missing from serialization structs. Cross-reference these against backup/CSV/CloudKit code.

Signal 4: Multiple systems touch the same data. Count how many systems read/write each field. A field serialized across backup + CSV + CloudKit + UI = 4 consumers = high risk. A field only in one view = low risk.

Signal 5: Money, identity, and relationships. Fields with InCents/Price/Value/Cost, identity fields (cloudSyncID, ownerUserRecordID), and @Relationship properties have higher consequences when gaps exist.

Signal 6: The "looks clean" feeling (meta-signal). When you feel confident about a domain without having produced its required artifact — that IS the signal to stop and do the work. Confidence without evidence is the #1 predictor of shallow work.

Risk-Ranking Output

Before starting Domain 1, produce a risk-ranking table:

Risk Ranking for [Model]:
  GO DEEP:
    1. CSV import (Signal 2: 27 export vs 11 import — 16-field asymmetry)
    2. Price fields (Signal 5: 6 currency fields across 3 serialization targets)
    3. Fields added since Build 24 (Signal 3: 4 new fields in last 3 months)
  QUICK OK:
    4. Backup (Signal 1: prior audit found full coverage)
    5. Relationship integrity (low change rate, all cascade)
  NOT APPLICABLE:
    6. CloudKit (no CKRecord mapping code found)

This table determines where time is spent. Domains that touch "GO DEEP" items get deep verification. Domains that only touch "QUICK OK" items can use quick verification (labeled accordingly).

---

Step 0: Model Discovery

Scan the codebase and identify all data models. This step runs automatically before any audit and is also available standalone via /data-model-radar models.

How to Find Them

IMPORTANT: Models can live anywhere under Sources/, not just Sources/Models/. Scan the full tree.

1. Search for @Model classes across ALL of Sources/: Grep pattern="@Model" glob="**/*.swift" path="Sources/"
2. Search for Core Data entities if applicable: Glob pattern="**/*.xcdatamodeld"
3. Search for Codable structs used in serialization: backup structs, export structs
4. Search for relationship models: Grep pattern="@Relationship" glob="**/*.swift" path="Sources/"
5. Check for recently changed models: git log --since="3 months ago" --name-only --diff-filter=M -- "Sources/**/*.swift" (note: ** not just Sources/Models/)

Common locations missed if only checking Sources/Models/:

• Sources/Features/*/ (feature-specific models like ScoutBookmark, ScoutRecentScan)
• Sources/Data/ or Sources/Database/
• Root of Sources/ itself

Risk Criteria

| Risk | Criteria | |------|----------| | High | Many fields (>20) + multiple serialization targets + external sync or externalStorage | | Medium | Moderate fields (10-20) + some serialization | | Low | Simple model ( 2.0` embed a threshold. Is the threshold reasonable? Is it documented? Could it be a user-configurable setting?

• Circular dependencies: Property A reads property B which reads property A. SwiftData models can create subtle cycles through relationship traversal.
• Calendar/date correctness: Properties computing durations (assetAge, daysRemaining) that use hardcoded values like 365.25 instead of Calendar APIs. Check for leap year handling, timezone assumptions.
• Currency computation safety: Properties combining *InCents fields. Verify they handle nil correctly and don't accidentally mix dollars and cents.

Method (Deep):

1. Grep the model file and its extensions for var.*:.*{ (computed properties with getters)
2. For each computed property that involves arithmetic, date math, or chained optionals, read the implementation
3. Check: are the inputs always available when this property is accessed? What happens when they're nil?
4. For currency computations, verify consistent units (all cents, no mixed dollars/cents)

Method (Quick):

1. List computed properties from the model file
2. Check only currency and date computations
3. Label grade as (quick)

Output per finding: The property, what it computes, what's wrong, and a concrete example of incorrect output.

Domain 2: Serialization Coverage enumerate-required

MANDATORY CHECKLIST — verify each target explicitly:

For the model being audited, check ALL applicable serialization targets. Do not skip any.

• [ ] Backup struct — Read the BackupXxx struct. Diff every model field against backup fields. List gaps.
• [ ] CSV export — Find the CSV export code (e.g., CSVExportManager, ExportManager). Read it. List which model fields map to CSV columns and which don't.
• [ ] CSV import — Find the CSV import code (e.g., CSVImportManager). Read it. List which CSV columns map back to model fields. The export→import gap is where data loss hides.
• [ ] CloudKit sync — Find CKRecord mapping code (e.g., CloudSyncManager, SharedZoneSyncManager). List synced fields.
• [ ] JSON API — If the model receives data from an API, check the response mapping.

Do not report a target as "covered" without reading the actual code. "Backup looks complete" without reading BackupItem is not verification.

Method:

1. Read the model — list all stored properties (exclude `@Trans

…

Source & license

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

• Author: Terryc21
• Source: Terryc21/radar-suite
• License: Apache-2.0
• Homepage: https://github.com/Terryc21/radar-suite

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