Imported from vishalkhondre/unearth (skills/07-data-model/SKILL.md). Install upstream with npx skills add vishalkhondre/unearth --skill 07-data-model. Copyright stays with the author.

Data Model

Discovers every data entity in the codebase — what gets persisted, where it's stored, how it's shaped for different consumers, and which capabilities own it. Classifies entities by type, maps storage mechanisms, traces cross-project projections, and identifies data model risks.

Without this step, the agent knows what the system does (capabilities) but not what data it manages. Data model understanding is essential for migration planning, database decomposition, and identifying hidden coupling through shared entities.

Pipeline Position

Inputs

Required

• outputs/05-components-*.md — Business component inventories (Section 3) for entity file locations and data store references
• outputs/06-capabilities.md — L1/L2 capability list (Section 5) for mapping entities to capabilities
• outputs/03-external-systems.md — Section 2 (External Systems Inventory) for data store technologies and connection details

Optional (improves results)

• outputs/00-recon.md — Section 3 (Technology Stack) for knowing which ORM/data frameworks to look for
• Stack adapter for the detected technology (provides entity detection patterns)
• Database migration files or schema scripts (if present in the repo)

When to Use

Use when:

• You need to understand what data the system manages
• You're planning a database migration or decomposition
• You need to identify data coupling between capabilities (shared entities)
• You're preparing for blueprint comparison or tech debt assessment

Do not use when:

• 06-capabilities has not been run (you need capability ownership context)
• The system is stateless with no persistent data (rare but possible)

Process

Step 1: Load Upstream Context

Read the upstream outputs. Extract:

• From 05-components-*.md: Entity/model file locations, data store references per component
• From 06-capabilities.md: L1 capabilities for ownership mapping
• From 03-external-systems.md: Data store technologies (relational, document, graph, blob, cache)

CHECKPOINT: The agent must know which data store technologies are
in use and where entity files are located before scanning.

Step 2: Discover Storage Entities

Scan for entities that are persisted to a database. Detection patterns vary by storage technology:

Relational (SQL):

• Entity Framework: classes with DbSet<T> references in DbContext, [Table] attributes, migration files
• JPA/Hibernate: @Entity, @Table annotations, persistence.xml
• Django: classes inheriting models.Model
• ActiveRecord: classes inheriting ApplicationRecord or ActiveRecord::Base
• SQLAlchemy: classes inheriting Base or db.Model

Document (NoSQL):

• MongoDB: classes used with IMongoCollection<T>, [BsonId] attributes, collection name config
• Cosmos DB: classes with [CosmosContainer], partition key attributes
• DynamoDB: @DynamoDBTable annotations

Graph:

• Gremlin/Neo4j: vertex/edge definitions, graph traversal queries that reveal schema
• Look for vertex labels, edge labels, and property definitions in query strings

Blob/File:

• Classes representing file metadata stored alongside blob references
• Container/bucket name configurations

Cache:

• Classes serialized to Redis, Memcached, or in-memory cache

For each storage entity, record:

• Entity name and source file path
• Storage technology (SQL, MongoDB, Gremlin, Blob, etc.)
• Collection/table/container name (from config or attributes)
• Key fields (primary key, partition key, unique constraints)
• Owning project and business component (from S-05)

If a stack adapter is loaded, consult its "Entity Detection" section for framework-specific patterns.

Step 3: Discover Projections and DTOs

Scan for data shapes that are not persisted but carry data between layers:

For each projection/DTO:

• Name and file path
• Type (request, response, event, view model, projection)
• Owning project
• Maps to (which storage entity or entities it derives from)

Step 4: Map Entity Attributes

For the most important storage entities (those shared across capabilities or central to the domain), document the full attribute structure:

Focus on entities that are:

• Shared across 3+ capabilities (highest coupling risk)
• Central to the domain (the "core" entity that everything references)
• Complex (50+ fields, nested structures, dynamic properties)

For simpler entities, a summary (field count, key fields, storage) is sufficient.

Step 5: Map Entity Relationships

Identify how entities relate to each other:

For systems without formal FK constraints (e.g., MongoDB, Cosmos DB), pay special attention to implied references — string fields whose names suggest they point to another entity but have no database-level enforcement.

CHECKPOINT: Every entity should have its relationships mapped —
either explicit (FK, edge) or implied (string ID reference).
Entities with zero relationships are suspicious and should be
investigated (they may be orphaned or their relationships may
be coded in application logic rather than schema).

Step 6: Map Cross-Project Entity Usage

Trace how entities flow across project boundaries:

For each entity, record which projects reference it and in what form (same class, projection, view model).

Step 7: Align Entities to Capabilities

Map each storage entity to its owning L1 capability (from S-06):

Entities shared across 3+ capabilities are coupling hotspots and should be flagged.

Step 8: Identify Data Model Risks

Review the complete data model for:

• Missing primary keys — entities without explicit PK definitions
• Implied references without constraints — string ID fields with no FK enforcement
• Cross-store references — entities in different databases referencing each other
• High-coupling entities — entities shared by many capabilities
• Schema-less risks — entities in document stores with no schema validation
• Zero test coverage — entities whose persistence logic is untested
• Large/complex entities — entities with 50+ fields or deep nesting

Step 9: Compile Data Model Output

Assemble all findings into the output file.

Output Format

This skill produces a single Markdown file: outputs/07-data-model.md

Required Structure

# Data Model — {System Name}

> **Pipeline stage:** 07-data-model
> **Date:** {date}
> **Input:** outputs/03-external-systems.md, outputs/05-components-*.md, outputs/06-capabilities.md
> **Scope:** {list of repositories/projects}

---

## 1. Entity Inventory

### Storage Entities

| Entity | Source Project | Storage Technology | Collection/Table | Key Fields | File Path |
| --- | --- | --- | --- | --- | --- |
| {name} | {project} | {tech} | {collection} | {PK, partition} | {path} |

### Projections and DTOs

| Entity | Source Project | Type | Maps To | File Path |
| --- | --- | --- | --- | --- |
| {name} | {project} | {request/response/event/view model} | {storage entity} | {path} |

### Summary

| Category | Count |
| --- | --- |
| Storage entities | {n} |
| Projections / DTOs | {n} |
| View models (BFF) | {n} |
| Total entity types | {n} |

---

## 2. Entity Attribute Details

### {Entity Name} ({Storage Technology})

| Attribute | Data Type | Constraints | Business Meaning |
| --- | --- | --- | --- |
| {field} | {type} | {constraints} | {meaning} |

**Business rules:** {rules governing this entity}

{Repeat for key entities — those shared across capabilities or central to domain}

---

## 3. Entity Relationships

| Source Entity | Relationship | Target Entity | Type | Enforcement |
| --- | --- | --- | --- | --- |
| {source} | {description} | {target} | {FK/edge/embedded/implied} | {DB constraint / app logic / none} |

---

## 4. Cross-Project Entity Usage

| Entity | Core API | BFF / API Gateway | Frontend | Form |
| --- | --- | --- | --- | --- |
| {name} | {storage entity} | {view model / DTO} | {interface / type} | {same class / projection / duplicate} |

---

## 5. Capability Alignment

| Entity | Owning Capability | Shared? | Referenced By |
| --- | --- | --- | --- |
| {name} | {L1 capability} | {Yes/No} | {other L1 capabilities} |

### Coupling Hotspots

| Entity | Capabilities (count) | Risk |
| --- | ---:| --- |
| {name} | {n} | {HIGH/MEDIUM/LOW — why} |

---

## 6. Data Model Findings

### Missing Constraints

| Entity | Issue | Risk |
| --- | --- | --- |
| {name} | {what's missing} | {impact} |

### Cross-Store References

| Source Entity (Store A) | Target Entity (Store B) | Reference Field | Enforcement |
| --- | --- | --- | --- |
| {entity in DB A} | {entity in DB B} | {field name} | {app logic / none} |

### Schema Risks

| # | Finding | Entity | Severity |
| --- | --- | --- | --- |
| 1 | {description} | {entity name} | {HIGH/MEDIUM/LOW} |

---

## 7. Items Flagged [NEEDS VERIFICATION]

| # | Item | Why | Impact if Wrong |
| --- | --- | --- | --- |
| 1 | {finding} | {uncertainty reason} | {downstream consequence} |

Stack Adapter Hooks

This skill benefits from stack adapter input at:

• Step 2 (Storage Entities): Adapter provides ORM/data framework patterns. The .NET adapter knows DbSet<T>, IMongoCollection<T>, Gremlin query patterns, and [BsonId]/[BsonElement] attributes. The java-spring adapter knows @Entity, CrudRepository<T, ID>, and Spring Data MongoDB annotations.
• Step 4 (Entity Attributes): Adapter knows constraint annotation patterns ([Required], @NotNull, @Column(unique=true)).
• Step 5 (Relationships): Adapter knows navigation property and FK patterns specific to the ORM.

Evidence Standards

Common Rationalizations

Red Flags

• Entity inventory that only covers one project in a multi-project system
• Storage entities without any relationship mapping (every entity relates to something)
• No cross-project usage analysis (missing the BFF projection layer)
• No capability alignment (entities floating without ownership)
• Missing the "implied reference" analysis for document databases
• Entity count that seems low for the system complexity (may have missed model classes)
• No data model risks identified (every system has at least a few)
• Confusing DTOs with storage entities (or vice versa)

Verification

Before marking this skill complete, confirm:

• All storage technologies from S-03 are represented in the entity inventory
• Storage entities are discovered with file paths, storage type, and collection/table names
• Projections, DTOs, and view models are cataloged separately from storage entities
• Key entities have attribute-level documentation with constraints and business meaning
• Entity relationships are mapped (explicit FK/edge AND implied references)
• Cross-project entity usage is traced (core → BFF → frontend)
• Every storage entity is aligned to an owning L1 capability from S-06
• Coupling hotspots (entities shared by 3+ capabilities) are flagged with risk assessment
• Data model risks are identified (missing PKs, implied references, cross-store refs, schema-less risks)
• All uncertain findings are flagged as [NEEDS VERIFICATION]
• Output file is saved to outputs/07-data-model.md
• Output file follows the required structure from the Output Format section