---
name: analyze-data-model
description: "Use when interrogating the codebase to understand an entity, its fields, relationships, and data flows. Use when user says 'analyze data model', 'analizar modelo', 'understand entity', 'check schema', or asks about a specific entity or database field."
argument-hint: "[entity or field name]"
allowed-tools:
  - Read
  - Grep
  - Glob
  - AskUserQuestion
---

## Step 0 — Load configuration

Read `${CLAUDE_PLUGIN_ROOT}/config.yaml`.
If it does not exist, this skill can still operate on the codebase directly. Log a warning but continue.

Check if config defines any custom code paths or conventions that should guide the search (e.g., specific directories for models, migrations, etc.).

## Step 1 — Parse argument

From `$ARGUMENTS`, extract the entity or field name to investigate.
If no argument provided, ask the user what entity or field they want to understand.

Store as `{entity}`.

## Step 2 — Locate entity definition

Search the codebase for the entity definition:

1. **ORM models** — Search for class/interface definitions matching `{entity}`:
   - Glob: `**/*{entity}*.*` (case-insensitive approach — try variations)
   - Grep: `class {Entity}`, `interface {Entity}`, `@Entity.*{entity}`, `model {Entity}`
   - Check common model directories: `src/models/`, `src/entities/`, `app/models/`, `prisma/schema.prisma`

2. **Database schemas** — Search migrations and schema files:
   - Grep: `CREATE TABLE.*{entity}`, `createTable.*{entity}`, `tableName.*{entity}`
   - Glob: `**/migrations/**`

3. **DTOs and types** — Search for data transfer objects:
   - Grep: `{Entity}Dto`, `{Entity}Input`, `{Entity}Response`, `{Entity}Type`

If multiple matches found, present them and ask the user which one to focus on.

## Step 3 — Interrogate each field

For each field found in the entity definition, answer these questions:

| Pregunta | Cómo encontrarlo |
|----------|------------------|
| What does this field mean? | Check comments, JSDoc, variable name semantics |
| Where does the data originate? | Grep for assignments to this field |
| Who/what generates it? | Check constructors, factory methods, seed data |
| Under what condition is it created? | Check create methods, POST endpoints |
| When/how does it mutate? | Grep for update/set operations on this field |
| What validations exist? | Check decorators, validators, constraints |
| What are the possible values? | Check enums, unions, DB constraints |
| Is it nullable? | Check schema definition, TypeScript types |
| Is it indexed? | Check migration files, schema decorators |

Build a comprehensive field table:

| Campo | Tipo | Nullable | Default | Validaciones | Origen | Mutaciones |
|-------|------|----------|---------|-------------|--------|-----------|
| {field} | {type} | {yes/no} | {value} | {rules} | {source} | {when/how} |

## Step 4 — Config parameter interrogation

If the entity involves configuration or environment variables, also investigate:

| Config | Dónde se define | Valor por defecto | Dónde se usa | Qué pasa si falta |
|--------|----------------|-------------------|-------------|-------------------|

Search for:
- `process.env.{RELATED_VARS}`
- Config files referencing the entity
- Feature flags that control behavior for this entity

## Step 5 — Map relationships

Search for references to the entity from other files:

1. **Foreign keys** — Grep for `{entity}Id`, `{entity}_id`, references in migrations
2. **ORM relations** — `@ManyToOne`, `@OneToMany`, `@ManyToMany`, `belongsTo`, `hasMany`, `references`
3. **Imports** — Which files import this entity
4. **Type references** — Where this entity is used as a type

Build a relationship map:
```
{Entity} ──1:N──▶ {RelatedEntity}
{Entity} ◀──N:1── {ParentEntity}
{Entity} ──N:M──▶ {OtherEntity} (via {JoinTable})
```

## Step 6 — Check migrations

Search migration files for this entity:
- Glob: `**/migrations/**`
- Grep: `{entity}`, `{table_name}`

List all migrations that touch this entity, in chronological order:
1. {date} — Created table with columns: ...
2. {date} — Added column {field}: ...
3. {date} — Added index on {field}: ...

## Step 7 — Check consumers and endpoints

Find all API endpoints and consumers that read or write this entity:

1. **REST endpoints** — Grep for route definitions mentioning the entity
2. **GraphQL resolvers** — Grep for resolver/query/mutation definitions
3. **Event handlers** — Grep for event listeners that process this entity
4. **Scheduled jobs** — Grep for cron/scheduled tasks involving this entity
5. **Message consumers** — Grep for queue/topic consumers

For each consumer:
| Endpoint/Consumer | Método | Lee campos | Escribe campos | Validaciones |
|-------------------|--------|-----------|---------------|-------------|
| {path} | {GET/POST/...} | {fields} | {fields} | {rules} |

## Step 8 — Output

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🗃️ DATA MODEL ANALYSIS: {Entity}
   Source: {file_path}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

━━ CAMPOS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{field table from Step 3}

━━ ORIGEN DE DATOS ━━━━━━━━━━━━━━━━━━━━━━━━━━━
{For each field: where data comes from and how it is generated}

━━ RELACIONES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{relationship map from Step 5}

━━ VALIDACIONES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{All validation rules found, grouped by field}

━━ MIGRACIONES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{chronological migration history from Step 6}

━━ ENDPOINTS / CONSUMERS ━━━━━━━━━━━━━━━━━━━━━
{consumer table from Step 7}

━━ PREGUNTAS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{Questions that could not be answered from code alone}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```