rlaope/oh-my-hermes / skills/omh-backend
omh-backend
Verified[omh] Designing an API, server, or data-layer change: prepare server, API, and data-layer contracts — auth boundary, error paths, response shape, and schema/migration discipline — before implementation. Use when the user says: backend, back-end, back end, backend skill, server side, server-side, api design, api contract.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.4 KB |
| references/consumer-impact.md | markdown | 4.1 KB |
| references/contract-tests.md | markdown | 4.4 KB |
| references/inbound-and-async.md | markdown | 5.7 KB |
| references/schema-migration.md | markdown | 3.2 KB |
| references/service-contract.md | markdown | 14.8 KB |
references/schema-migration.md
View on GitHub# Schema and Migration Discipline
Load this when the prepared backend change touches storage. OMH writes no migration and applies none; this is the order the plan has to have before an executor runs anything.
## 1. Expand, backfill, switch, contract
A schema change that is deployed as one step is a schema change that cannot be rolled back once traffic has touched it. Split every storage change into four:
1. **Expand.** Add the new column, table, or index. Nothing reads it. Old code keeps working unchanged. This step is reversible by dropping what was added.
2. **Backfill.** Populate the new shape from the old one in bounded batches. Reversible by ignoring the new shape. Name the batch size and the pause between batches; an unbounded backfill on a live table is an outage.
3. **Switch.** Move reads, then writes, to the new shape. This is the step where a rollback means reverting code, not reverting data.
4. **Contract.** Drop the old column, table, or index -- only after the switch has been observed stable for a named period. This step is irreversible.
Each step names its own rollback point. If a step's rollback is "restore from backup", that step is a blocker until it is split further.
## 2. The blocker list
Any of these is a blocker until the plan resolves it explicitly:
- A `DROP` or destructive `ALTER` in the same deployment as the code that stops using it.
- A backfill with no batch bound, no progress measure, and no resume point.
- A rename presented as one step. A rename is expand plus backfill plus switch plus contract, always.
- A new `NOT NULL` column with no default on a populated table.
- An index creation on a large table without naming whether the engine builds it concurrently.
- A migration that must run inside the same transaction as a long backfill.
- A statement that cannot run in a transaction (`CREATE INDEX CONCURRENTLY`) inside a migration the tool wraps in one. Mark that migration non-transactional in the tool and keep the statement alone in it; dropping `CONCURRENTLY` to make the tool accept it turns an online build into a write lock.
- Two deployments that must land in a specific order with nothing enforcing the order.
## 3. Compatibility window
Between expand and contract, both shapes exist and both must work. The plan states:
- Which application versions are expected to be live at the same time.
- What the old code does when it encounters a row written by the new code, and the reverse.
- How long the window stays open, and what closes it.
A migration plan with no stated compatibility window is a plan that assumes atomic deployment, which no multi-instance service has.
## 4. What counts as evidence
| Claim | Evidence that supports it |
| --- | --- |
| The migration is written | the migration file exists in the diff |
| The migration applies | an observed run against a database, with its output |
| The backfill completed | observed row counts before and after, not the script's exit code alone |
| The switch is safe | observed reads and writes on the new shape under real traffic shape |
| The contract step is safe | an observed stable period after the switch, with the duration named |
A prepared plan supports none of these. Every row above stays `not_observed` until the executor reports the observation.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |