AGENT SKILL

data-model

The craft of a data change: for each entity, the migration, the existing rows, the indexes, the queries, the backfill, the rollback and the order of shipping. Use when a plan adds or changes a table, a field, an index or a migration.

License 许可
MIT
所属仓库
lamtran8401/nook
最近更新
2026-10-27
Stars
★ 0
Forks
0

01 前言 Front Matter

name
data-model
description
The craft of a data change: for each entity, the migration, the existing rows, the indexes, the queries, the backfill, the rollback and the order of shipping. Use when a plan adds or changes a table, a field, an index or a migration.
user-invocable
false

03 SKILL.md 正文

Goal: the cost, the order and the way back of a data change, visible before the owner approves the plan. Data changes are the hardest to undo. Think about the existing rows first. Work from the code and the migration files of the areas. Never connect to a database, and never run a migration.

Order

  1. List the entities, tables and fields that change, each with the file and line where it is defined today: the entity, the schema file or the migration.
  2. For each change:
    • the migration: what it does, and whether it locks or rewrites a large table;
    • the existing rows: nulls, defaults, constraints that old rows break;
    • the indexes: which the new queries need, and what an index build costs;
    • the queries and the code that read the table.
  3. The backfill, when old rows need new values: how, in which batches, who runs it.
  4. The rollback: how to undo the change, and what data the undo loses. Say plainly when a step cannot be undone.
  5. The order of the migrations and the code: expand, deploy the code, then contract.
  6. What you could not check: the size of the tables, the settings of production.
Shipment (bff src/entities/shipment.ts:12, table shipments)
- Change: index on status. Migration: additive; the build locks writes on a large table unless it runs concurrently.
- Existing rows: unchanged. Queries: list.ts:51 filters on status and uses the index.
- Backfill: none. Rollback: drop the index; loses nothing.
Risks: the index build at peak. Order: the index, then the bff, then the frontend. Hard to undo: none.
Not checked: the size of shipments in production; whether the migration tool runs concurrent index builds.

Gotchas

  • A migration that is safe on an empty table can lock a large one. Say what you do not know about the size.
  • Prefer expand, then contract: add the new form, move the code, then remove the old form.
  • A step that cannot be undone is the owner's to time. Say so.
  • Do not guess a table size or a production setting. Put it under Not checked.
  • A new query with no index is a gap, also when the plan does not name the index.

04 同仓库更多 Skills

lamtran8401
lamtran8401/nook

yolo

Run an item alone from its state to the owner's accept: the lead runs the phases, records each guess, passes the plan gate with proceed, and stops at a stop rule. Use when the owner types /yolo with an id, a prompt, or nothing.

★ 0
lamtran8401
lamtran8401/nook

write-walkthrough

Write walkthrough.md, the explanation of finished work: what works now in plain words, the changed files, where to start reading, the key code, the met criteria, how to try it, the risks. It is the source of the Walkthrough tab of the web app. Use after /qa, or for a question about the code.

★ 0
lamtran8401
lamtran8401/nook

wiki-tidy

Find what is wrong in the wiki: broken links, pages with no index line, lines too near the code, stale epic pages, topics with no source, two pages on one topic, adjectives with no example. Fix the mechanical part after one yes; list the rest. Use when the owner says tidy the wiki, or after many pages changed.

★ 0
lamtran8401
lamtran8401/nook

wiki-merge

Merge related wiki pages into one complete page: the pages of the features of one process or epic become one page with the flow from end to end. The old pages move to the archive after the owner's yes, and their links point at the new page. Use when the owner says merge these pages, or when wiki-tidy finds pages on one topic.

★ 0
lamtran8401
lamtran8401/nook

wiki-ask

Answer a question from the wiki: the index first, then only the pages whose line matches, an answer in a few lines with a link to each page. Use when the owner asks what the wiki says, or asks why or how about a known topic. Not to add a page: wiki-add.

★ 0
lamtran8401
lamtran8401/nook

wiki-add

Keep the lesson of a source in the wiki: a page in the shelf business/ or tech/ with its main points, a real example for each, the gotchas and the link of the source; written after the owner's yes. Use when the owner says add this to the wiki, keep this, or gives a PRD, a ticket, notes or an article to keep.

★ 0