moai-domain-db-docs

name	moai-domain-db-docs
description	Parses DB migration files (Prisma, Alembic, Rails, raw SQL) and keeps .moai/project/db/schema.md, erd.mmd, migrations.md in sync. Powers the PostToolUse hook and /moai db refresh/verify subcommands.
license	Apache-2.0
compatibility	Designed for Claude Code
allowed-tools	Read, Write, Edit, Grep, Glob, Bash, TaskCreate, TaskUpdate
user-invocable	false
metadata	{"version":"1.0.0","category":"domain","status":"active","updated":"2026-04-20","tags":"db, schema, migration, documentation, sync, drift"}
triggers	{"keywords":["db docs","schema sync","migration parse","erd update"],"agents":["expert-backend"],"phases":["run","sync"]}

moai-domain-db-docs: DB Documentation Sync Skill

Purpose: Consume .moai/cache/db-sync/proposal.json and update the three DB documentation files (schema.md, erd.mmd, migrations.md) in .moai/project/db/.

SPEC: SPEC-DB-SYNC-001

---

Invocation Modes

This skill is invoked in two ways:

1. PostToolUse approval flow (via orchestrator): After the user selects "Apply" in the 3-option AskUserQuestion dialog, the orchestrator invokes this skill with proposal.json.

2. Direct subcommand: Via /moai db refresh (full rebuild) or /moai db verify (drift check).

---

Recursion Guard (REQ-019)

Before writing any file, check that the target path is NOT in the Excluded Patterns:

• .moai/project/db/**
• .moai/cache/**
• .moai/logs/**

If the target matches an excluded pattern, abort silently. This is a skill-level guard complementing the hook-level guard (REQ-004).

---

Phase A: Apply Proposal (REQ-013, REQ-016, REQ-017, REQ-018)

Triggered when user selects "Apply" in the approval flow.

A1: Read proposal.json

Read .moai/cache/db-sync/proposal.json

Extract:

• file_path: original migration file
• parsed_content: normalized schema representation
• timestamp: ISO-8601 creation time

A2: Update schema.md (REQ-016)

Rules for in-place update:

1. Read existing .moai/project/db/schema.md.
2. Identify sections delimited by ## headers.
3. For each table/collection referenced in parsed_content:
   • If a matching row exists, update column_count and last_migration_file.
   • If no matching row, append a new row preserving _TBD_ in user-managed columns.
4. Do NOT overwrite user-edited descriptions or _TBD_ markers.
5. Write updated file using Edit tool.

A3: Regenerate erd.mmd (REQ-017)

Rules:

1. Read existing to extract the comment header block (lines starting with ).