Profiles a single table for migration by assembling deterministic context from catalog files, reasoning over six profiling questions (classification, primary key, foreign keys, natural vs surrogate key, watermark, PII), presenting results for user approval, and writing the approved profile to the table catalog file. The profile drives materialization, test generation, and model generation downstream.

/profiling-table <schema.table>

Argument is the fully-qualified table name. The skill asks if missing. The writer procedure is read automatically from the catalog's scoping.selected_writer field.

Trigger phrases: "profile a table", "classify a table", "what kind of model is this table", "determine PK, FK, watermark, or PII for a migration target".

• manifest.json must exist in the project root. If missing, run ad-migration setup-source first.
• catalog/tables/<table>.json must exist. If missing, run /listing-objects list tables to see available tables.
• scoping.selected_writer must be set in the table catalog. If missing, run Skill Analyzing Table first.
• The skill checks profiling readiness through migrate-util ready and stops on the surfaced code if the object is not ready.

uv run --project <shared-path> profile context --table <table>

The CLI reads the selected writer from the table's catalog scoping section. Output shape is enforced by the ProfileContext Pydantic model in lib/shared/output_models.py:

• catalog_signals -- PKs, FKs, identity columns, unique indexes, change capture, sensitivity classifications
• writer_references -- outbound references from the writer procedure with column-level read/write flags
• proc_body -- full SQL body of the writer procedure
• columns -- target table column list with types and nullability
• related_procedures -- related procedure context when referenced by the writer

The LLM reads the context JSON and answers six profiling questions using signal tables and pattern matching rules from the profiling-signals reference.

Profile is presented as a structured summary. If a required question (Q1, Q2, Q4, Q5) cannot be answered with reasonable confidence, the ambiguity is presented to the user for guidance. The user must explicitly approve before the profile is persisted.

mkdir -p .staging
# Write profile JSON to .staging/profile.json
uv run --project <shared-path> profile write \
  --table <table> \
  --profile-file .staging/profile.json; rm -rf .staging

The profile section follows table_catalog.json#/$defs/profile_section.

Determines materialization strategy, dbt tests, and whether SCD2 history logic is needed.

Write-pattern signals:

Column shape signals:

classification object fields:

Required for unique_key in incremental models. Missing it forces full-refresh or produces duplicates.

Signals beyond catalog PKs:

primary_key object fields:

Needed for relationships tests and detecting role-playing / degenerate dimensions.

FK type resolution:

foreign_keys[] entry fields:

Determines whether the model calls dbt_utils.generate_surrogate_key and whether the incremental unique_key is a raw column or generated hash.

Signals:

natural_key object fields:

Without a watermark column, the model can only be table (full refresh). Operationally unacceptable for large fact tables.

Signals:

watermark object fields:

Does not affect SQL correctness. Missing PII detection is a compliance risk.

Signals beyond catalog sensitivity classifications:

pii_actions[] entry fields:

Suggested action meanings:

Every decision point in the profile includes a source field indicating how the answer was derived:

Catalog signals are treated as facts. The LLM fills in what the catalog does not answer.

{
  "profile": {
    "status": "ok",
    "writer": "silver.usp_load_dimcustomer",
    "classification": {
      "resolved_kind": "dim_scd1",
      "rationale": "MERGE with WHEN MATCHED THEN UPDATE on all non-key columns. No valid_from/valid_to columns present, ruling out SCD2.",
      "source": "catalog+llm"
    },
    "primary_key": {
      "columns": ["CustomerKey"],
      "primary_key_type": "surrogate",
      "rationale": "CustomerKey is an identity column (catalog PK constraint PK_DimCustomer). Auto-increment seed=1, increment=1.",
      "source": "catalog"
    },
    "natural_key": {
      "columns": ["CustomerAlternateKey"],
      "rationale": "MERGE ON clause uses CustomerAlternateKey to match source to target, confirming it as the business key.",
      "source": "llm"
    },
    "watermark": {
      "column": "ModifiedDate",
      "rationale": "Proc WHERE clause filters on ModifiedDate > @LastLoadDate. DATETIME2 type confirms suitability as watermark.",
      "source": "llm"
    },
    "foreign_keys": [
      {
        "column": "GeographyKey",
        "references_source_relation": "silver.DimGeography",
        "references_column": "GeographyKey",
        "fk_type": "standard",
        "rationale": "Declared FK constraint FK_DimCustomer_Geography. Single column, single dimension -- standard FK.",
        "source": "catalog"
      }
    ],
    "pii_actions": [
      {
        "column": "EmailAddress",
        "entity": "email_address",
        "suggested_action": "mask",
        "rationale": "Column name matches PII pattern 'email'. NVARCHAR type confirms string content.",
        "source": "llm"
      },
      {
        "column": "Phone",
        "entity": "phone_number",
        "suggested_action": "mask",
        "rationale": "Column name matches PII pattern 'phone'.",
        "source": "llm"
      }
    ],
    "warnings": [],
    "errors": []
  }
}