migration-backlog

Plain-language prompts (alternatives to /migration-backlog)

Any of these phrases should trigger this skill when spoken in natural language — please invoke /migration-backlog when the user asks:

• "What migrations are left?"
• "Show me the migration backlog"
• "What NEW-NNN entries are still planned?"
• "Which migrations are deferred and why?"
• "Is NEW-065 built?"
• "Next migration to work on?"
• "What's blocking migration X?"

User Input

$ARGUMENTS

Arguments map to the underlying CLI subcommands of scripts/migration-backlog.ts:

• Empty or summary → default summary with next-actionable + deferred tables
• list [status] → full list, optionally filtered (planned, built, deferred, retracted)
• show <tag> → details for a single entry (e.g., show NEW-047)
• next → only the planned-entries-with-no-blockers subset

Workflow

1. Run the reporter script:

   npx tsx scripts/migration-backlog.ts $ARGUMENTS
   

2. Output the reporter's markdown verbatim to the user. Do NOT summarize, paraphrase, strip emoji, or cut sections. The reporter produces a complete report and the user wants to see all of it. Only add a brief sentence before or after the report if you're highlighting something specific (e.g., "Here's the current migration backlog:" or "NEW-065 is blocked by NEW-079.").

3. If the user asks follow-up questions about a specific tag's dependencies or history, use show <tag> on that tag — don't re-run the full summary.

What the registry tracks

The registry at scripts/lib/migration-backlog-data.ts is the authoritative source for:

• Every NEW-NNN migration tag from the §13 inventory tables across all red team passes (Bucket B, Pass 2 P2-A/P2-B, Pass 3+4 P34, v3.1 Workshop 3)
• Current implementation state per entry: built / built (schema) / built (reduced) / deferred / retracted / planned
• The migration file and PR number for built entries
• The source decision reference (e.g., B3, P34.3, Workshop 3 / §3.12.6)
• Free-text notes explaining scope reductions and deferral reasons
• Dependency hints: what each migration blocks + what blocks it

CI gate

A companion script scripts/validate-migration-backlog.ts runs in CI (via .github/workflows/migration-backlog-lint.yml) and fails the build on registry drift:

• Every migration file 047+ must have a matching built* entry
• Every file: value in the registry must exist on disk
• No duplicate tags
• built* entries must have both file and pr set (unless they use implemented_by to point at a primary entry)
• planned / deferred / retracted entries must have file: null and pr: null

This means: you cannot ship a migration without updating scripts/lib/migration-backlog-data.ts — the CI gate blocks the PR.

How this relates to the §13 inventory tables in the spec

If your project maintains narrative documentation tables over the migration data, when they drift from the registry, the registry wins — update the docs to match, not the other way around.

Cross-reference from /build-order

The /build-order scanner reads feature specs' **Required Migrations**: NEW-NNN frontmatter line and cross-references it against this registry. A feature spec with an unbuilt migration dep gets classified as blocked and shows the blocking tag in its "Waiting on" column — the scanner merges F## feature blockers and NEW-NNN migration blockers into one list.

The handshake is direct: scripts/build-order/scan.ts imports MIGRATION_BACKLOG directly from scripts/lib/migration-backlog-data.ts and resolves alias entries (those with implemented_by) inline at startup. No TSV intermediary is used. scripts/migration-backlog-dump.ts is a separate utility that emits TSV for external/bash consumers — it is not called by the build-order scanner.

This means a dev running /build-order at the start of their day gets a unified view: "these features are ready; these are blocked by an upstream feature; these are blocked by an unbuilt migration." See .claude/skills/build-order/SKILL.md "How dependencies are resolved" for the matching side of the handshake.

When to use this skill

• At the start of a session when deciding which migration to write next
• When the team asks "what's left?" for migration work
• When onboarding a new dev who needs to understand the backlog
• When a feature PR depends on an unbuilt migration — use show <tag> to check its status
• Before running migrations locally — pair with npx tsx scripts/migrate.ts so you know what new tables / columns landed

When NOT to use this skill

• Not for feature spec status — use /build-order for that (different concept, different registry)
• Not for schema introspection — the registry tracks decisions, not the live Postgres state. Query schema_migrations directly for that.
• Not during active migration-writing — run the validator (npx tsx scripts/validate-migration-backlog.ts) instead, which checks drift; the reporter is a human-readable summary not a lint.

Constraints

• Read only. The reporter never modifies the registry or any migration file.
• Fast. Runs in under 1 second; the registry is a single TypeScript file with ~55 entries.
• Type-safe. tsc catches typos in tags, statuses, and required fields at edit time — mistakes surface before they hit CI.