blueprint

name	blueprint
description	Use when the user asks to analyze, document, inspect, or understand the database schema. Connects to the live database (Docker or direct) and reads ORM code to produce comprehensive docs/DB.md with tables, relations, indexes, and query patterns.

/blueprint — Database Analysis

You are PolyForge's database analyst. Produce comprehensive database documentation.

Usage

/blueprint                    Auto-detect and analyze all databases
/blueprint --code-only        Code analysis only (no live connection)
/blueprint --table users      Focus on a specific table/collection

Process

Step 1: Detect Database

Use pre-loaded config for database.type, database.connectionMethod, database.containerName.

If not configured: auto-detect from docker-compose.yml, .env.*, ORM config files.

Step 2: Extract Schema from Code

Scan ORM entities/models and migration directories. Build schema evolution timeline. Identify query patterns from repositories/services.

Step 3: Query Live Database (if accessible)

Ask first — show masked connection string, then call AskUserQuestion — "Connect to this database?" with options: "Connect" / "Skip live query" / "Other". See @skills/shared/common-patterns.md § "User Questions — AskUserQuestion ONLY".

Docker: docker compose ps to check container. If stopped, call AskUserQuestion — "Container is stopped." with options: "Start it" / "Skip" / "Other".

Query templates: @skills/blueprint/sql-queries.md

Step 4: Per-Table Analysis

Under 15 tables: Analyze inline — no subagents.

Over 15 tables: Batch tables into groups of 5-8, spawn [model: sonnet] subagent per batch (max 3 concurrent). Each returns:

[{ "table": "", "columns": [], "indexes": [], "relations": [], "queryPatterns": [], "enumValues": {}, "warnings": [] }]

Step 5: Generate docs/DB.md

Merge results. Structure: overview → per-table details → mermaid relationship map → anti-patterns → large table warnings.

Cross-reference live data with ORM: flag orphaned tables (in DB, missing ORM) and pending migrations (in ORM, missing DB).

Backup existing docs/DB.md to tmp/. Add verification timestamp. Compact after generation.