Skip to content

feat(architecture): add map-data, an ERD from the declared schema, offline #4648

Closed

Description

@kyle-sexton

Part of #4639. Not blocked by map-dependencies.

Problem

People often need a system's entities and their relationships drawn, and the diagram usually lives in a
hand-drawn document that goes stale within a month. No skill produces an as-built ERD from the
repository. Comparable tools elsewhere usually need a live database connection, which rules them out in
review, in CI, and on machines without credentials. plugins/architecture/skills/ on main has no
map-data.

Evidence

Verified this pass (main a6ba321):

  • The skill does not exist.
  • /planning:design already emits an ERD for a design (entity-relationships.md), in the dialect set
    by diagram_dialect.data (mermaid|dbml, default mermaid)
    (plugins/planning/skills/design/SKILL.md:175, docs/conventions/authoring-formats/README.md). An
    as-built ERD should reuse that key rather than add a second one for the same kind of artifact. This
    is the epic's dialect decision, with a recommended answer here.

Proposed approach

/architecture:map-data [--scope module|all] [--include-columns]

Source tiers, where the first available source wins and the artifact names which one it used:

  1. a model definition file, when the project generates its schema from one
  2. ORM mapping configuration (entity configurations, attributes, fluent mappings)
  3. migration history, replayed to a final shape
  4. a live connection: only when explicitly requested, never the default

Cardinality and optionality come from the same declarations: foreign keys, navigation collections and
nullability. The default scope is one module where module boundaries can be derived. Columns are
opt-in.

Files:

  • new plugins/architecture/skills/map-data/{SKILL.md,scripts,evals}
  • plugin.json, CHANGELOG.md, README.md
  • docs/conventions/authoring-formats/README.md consumers table, if diagram_dialect.data is reused

Acceptance criteria

  • With no database connection available, a fixture produces an ERD with correct cardinality from
    its declared mappings.
  • Per-module scoping produces a readable subset.
  • The artifact states which source tier it used.
  • A mismatch between a migration and an ORM mapping in a fixture is reported, not silently resolved.
  • Column detail appears only with --include-columns.
  • The dialect comes from diagram_dialect.data, or the epic records why not.

Constraints and gotchas

  • No live connection unless explicitly requested. The offline default is what makes the skill usable
    in review and CI.
  • Out of scope: data volumes, indexes, query performance, lineage and ETL, and any production data
    access.
  • Follow .claude/rules/skill-bodies-state-current-rules.md, keep the description under 1024
    codepoints, and bump the version and add a CHANGELOG entry.

Context

Source: local handoff item 20260907-094204-map-data-skill-proposal.md (retired into this issue).
Parent epic: #4639. Related: #3814 (diagram-dialect convention).

Activity

  1. kyle-sexton commented on Sep 29, 2026

    @kyle-sexton
    MemberAuthor

    Refs #4648. The 2026-09-29 audit of the Cursor run found code defects in map-data. #5392 (T10, T11) fixes them:

    • One-to-one relations now draw as ||--o| (required) or |o--o| (optional).
    • More uniqueness declarations are read, so a one-to-one no longer draws as one-to-many. DBML uses the declared referenced column.
    • ALTER TABLE in a migration is replayed, or the migration tier is refused by name.
    • An EF tier that loses and cannot be read no longer blocks a winning Prisma record.
    • Nodes are keyed by module when two modules declare the same entity name.

    The EF reader is still a narrow subset of the fluent API, and the skill's description and SKILL.md now say so. The standard EF Core shape (a lambda HasForeignKey, IEntityTypeConfiguration<T>, requiredness inferred from nullability) is tracked in #5403.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions