Mermaid Diagram Review

The user has shared a diagram and wants honest, rigorous feedback. Your default mode is constructive critique against the constitution, not endorsement.

When to use this skill

If the user is asking for an initial design (no diagram yet), use the commerce-database-architecture skill instead.

If the user is asking how to implement the change, use the schema-evolution-workflow skill instead.

Pre-flight

1. Load constitution + principles + boundaries + eventing files
2. Load current-schema-state.md. If stale, run postgres-schema-introspection.
3. Skim last 20 entries of schema-change-log.md.

Required output (five sections, exact headings, never omit)

1. Constitutional violations

Numbered list. Per violation:

• Severity: BLOCKER | HIGH | MEDIUM | LOW
• Section: § number from the constitution
• Finding: what's wrong, in one sentence
• Why it matters: one sentence of impact
• Evidence: the specific table/relationship in the diagram

The full default-checks matrix (15 checks with severity + constitution section) lives in default-checks.md. Run every check; each failure becomes a numbered finding above.

If zero violations: "No constitutional violations detected. Refinements follow."

2. Counter-proposal

If violations exist: an improved Mermaid erDiagram showing the corrected structure, plus a short prose explanation mapping each change to the violation it fixes. Include explicit module ownership for every entity (prefix or schema).

Use Mermaid's erDiagram syntax with PK / FK markers and cardinality:

erDiagram
  TENANCY_TENANTS ||--o{ CATALOG_PRODUCTS : owns
  CATALOG_PRODUCTS ||--o{ CATALOG_VARIANTS : "has variants"
  CATALOG_VARIANTS ||--o{ INVENTORY_BALANCES : "stocked at"
  INVENTORY_BALANCES ||--o{ INVENTORY_MOVEMENTS : "audited by"

  CATALOG_PRODUCTS {
    bigint id PK
    uuid public_id UK
    bigint tenant_id FK
    text sku
    text name
    bigint brand_id FK
    jsonb metadata
    timestamptz created_at
    timestamptz updated_at
    timestamptz deleted_at
  }

If zero violations: produce refinements (better indexes, JSONB promotions, partition recommendations) with the same diagram-and-prose format.

3. Migration plan

If the current schema (per current-schema-state.md) differs from the counter-proposal, fill the four-phase template in migration-template.md: Expand → Backfill → Cutover → Contract, each with exact SQL, lock impact, backward compatibility, and rollback.

Greenfield (no current state): "Greenfield — initial DDL only, no migration phases needed."

4. Test surface

Group by type. One sentence per test.

• Unit — pure logic
• Integration — schema + queries
• Tenant isolation — RLS positive + negative cases
• Migration — apply + rollback against production-like data
• Projection sync — outbox → Neo4j idempotency
• Concurrency — overselling, double-spend
• Idempotency — duplicate-request handling

5. Open questions

What you need from the user. Bullet list. If none: "No open questions — ready to proceed."

Behavioral rules

• Never silently accept a tenant-isolation violation. If the diagram has no tenant_id on tenant-scoped entities, that's the first BLOCKER.
• Never propose microservices in the counter-proposal unless the diagram is explicitly modeling a multi-service architecture and an ADR exists.
• Never put truth in a non-Postgres entity. If the diagram puts orders or inventory in Neo4j, that's a § X BLOCKER.
• Always cite section numbers. Section references make the feedback verifiable.
• Be direct. Don't soften "missing tenant_id" with "you might consider". Say "BLOCKER: § IV — products has no tenant_id."