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 Method