@ai-support-agent/cli 0.1.32 → 0.1.33-beta.1

package/dist/plugin/skills/backend-patterns/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: backend-patterns
+description: A collection of backend design and implementation patterns covering layering, input validation, N+1 queries and transactions, caching, error handling, authentication/authorization, rate limiting, structured logging, and background jobs, for NestJS / Django / Flask / Laravel / CakePHP. Use this when designing, implementing, or reviewing backend APIs, service layers, or jobs.
+---
+
+# backend-patterns: Backend Design & Implementation Patterns
+
+Target stacks: NestJS / Django / Flask / Laravel / CakePHP.
+Code examples favor NestJS, Django, and Laravel; Flask and CakePHP equivalents are noted alongside them.
+For interface conventions such as URL design and status codes, see the api-design skill.
+
+## Layering
+
+- Keep controllers (handlers) thin. Their only responsibilities are: accepting and transforming input, calling the service layer, and shaping the response.
+- Put business logic in the service layer. Conditional branching, calculations, and cross-resource consistency all belong here.
+- Keep data access isolated in a repository/ORM layer. Don't leak raw SQL or query-builder details into the service layer.
+- Structuring things so the same logic can be called from both a controller and a job (CLI or queue worker) is a good self-check for whether your layering is actually sound.
+
+```typescript
+// NestJS
+// Bad: business logic and data access live directly in the controller
+@Post()
+async create(@Body() body: any) {
+  const user = await this.userRepo.findOne({ where: { email: body.email } });
+  if (user) throw new BadRequestException('exists');
+  if (body.plan === 'pro' && !body.cardToken) throw new BadRequestException();
+  return this.userRepo.save({ ...body });
+}
+
+// Good: the controller only passes through; decisions live in the service layer
+@Post()
+async create(@Body() dto: CreateUserDto) {
+  return this.usersService.register(dto);
+}
+```
+
+In Django, keep views thin and push logic into a service module (e.g. `services.py`) or model methods. In Laravel, delegate from controllers to service/action classes, and push complex Eloquent queries into query scopes or repositories. In CakePHP, preserve the Controller → Table (model layer) separation.
+
+## Input Validation
+
+Use the framework's built-in validation mechanism. Hand-rolled chains of `if` statements are easy to miss cases with and hard to review.
+
+- NestJS: DTOs + class-validator + `ValidationPipe` (always enable `whitelist: true`)
+- Django: Forms / DRF Serializers
+- Flask: schema validation libraries such as marshmallow or pydantic
+- Laravel: FormRequest
+- CakePHP: Validator (the Table's `validationDefault`)
+
+```typescript
+// NestJS
+// Good: declare types and constraints via a DTO, and strip unknown fields with whitelist
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @Length(8, 72)
+  password: string;
+}
+// main.ts: app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
+```
+
+```python
+# Django REST Framework
+# Bad: passing request.data straight into the model (mass assignment)
+User.objects.create(**request.data)
+
+# Good: use a serializer to explicitly declare which fields are accepted
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ["email", "password"]  # avoid fields = "__all__"
+```
+
+```php
+// Laravel
+// Bad: mass-assigning $request->all() (is_admin etc. could be overwritten)
+User::create($request->all());
+
+// Good: use only FormRequest's validated() data, and keep $fillable minimal
+public function store(StoreUserRequest $request)
+{
+    return User::create($request->validated());
+}
+```
+
+The principle behind mass-assignment protection is the same everywhere: explicitly whitelist which fields may be accepted. Attributes tied to permissions or ownership — `is_admin`, `role`, `tenant_id`, and the like — should be set from server-side context (the authenticated identity), never from the request body.
+
+## Database
+
+### Detecting N+1 Queries and Batching Fetches
+
+Always be suspicious of queries issued inside a loop. During development, check actual query counts with a query log (Django Debug Toolbar, Laravel Telescope / `DB::listen`, TypeORM's `logging: true`).
+
+```python
+# Django
+# Bad: fetches the author one row at a time per article (1 + N queries)
+for article in Article.objects.all():
+    print(article.author.name)
+
+# Good: preload via JOIN / batch fetch
+for article in Article.objects.select_related("author"):
+    print(article.author.name)
+# Use prefetch_related for many-to-many and reverse relations
+```
+
+```php
+// Laravel
+// Bad: accessing $article->author inside a loop triggers N lazy-load queries
+$articles = Article::all();
+
+// Good: eager loading fetches everything up front
+$articles = Article::with('author')->get();
+```
+
+In NestJS + TypeORM, achieve the same with `relations` or `leftJoinAndSelect` on the QueryBuilder. With Prisma, use `include`.
+
+### Transaction Boundaries
+
+Identify the unit of work that must be "all succeed or all fail," and wrap exactly that unit in a transaction.
+
+- Open transactions in the service layer. Opening them in a controller or in an individual repository call leaves the boundary ambiguous.
+- Never put external API calls, email sending, or other long-running operations inside a transaction. Doing so extends how long locks are held, and if the external call fails and you roll back the DB, the external side effect can't be undone. Perform external effects after commit, or hand them off to a job queue.
+
+```python
+# Django
+# Good: confirming an order and decrementing stock happen in one transaction
+from django.db import transaction
+
+def confirm_order(order_id: int) -> None:
+    with transaction.atomic():
+        order = Order.objects.select_for_update().get(pk=order_id)
+        order.confirm()
+        order.save()
+        Stock.objects.filter(product=order.product).update(
+            quantity=F("quantity") - order.quantity
+        )
+    # Good: send the email only after commit
+    transaction.on_commit(lambda: send_order_mail.delay(order_id))
+```
+
+Laravel uses `DB::transaction(fn () => ...)`; NestJS + TypeORM uses `dataSource.transaction()` or a QueryRunner. In systems built around command/event sourcing with separate write and read models, a single command is typically the unit of consistency — don't try to force consistency across multiple aggregates into one transaction; instead, design the cross-aggregate effects as eventually-consistent follow-up processing.
+
+## Caching
+
+The default pattern is cache-aside: check the cache on read, and on a miss, fetch from the database and populate the cache.
+
+```typescript
+// NestJS (cache-aside skeleton)
+async getProduct(id: string): Promise<Product> {
+  const cached = await this.cache.get<Product>(`product:${id}`);
+  if (cached) return cached;
+  const product = await this.productRepo.findOneByOrFail({ id });
+  await this.cache.set(`product:${id}`, product, 300); // always set a TTL
+  return product;
+}
+```
+
+- Design assuming invalidation is hard. Combine explicit deletion on update with a TTL as a second line of defense, and decide per data type how much staleness is acceptable until the TTL expires. Standardize keys as `resource-name:id` so you can always identify what to invalidate.
+- Safe to cache: master/reference data, public content, expensive aggregate results — anything that looks the same to everyone and can tolerate some staleness.
+- Do not cache (or be extremely careful with): authorization decisions, entire responses containing personal information, or values that demand strict accuracy such as balances or inventory counts. Storing user-specific data under a key that doesn't include the user ID is a classic way to leak one user's data to another — avoid it absolutely.
+
+## Error Handling
+
+### Centralized Handlers
+
+Don't scatter exception handling throughout the codebase; consolidate it in the framework's centralized mechanism.
+
+- NestJS: Exception Filter (`@Catch()`)
+- Django: middleware / DRF's `EXCEPTION_HANDLER`
+- Flask: `@app.errorhandler`
+- Laravel: exception handling configuration in `bootstrap/app.php` (formerly the Handler class)
+- CakePHP: ErrorController / a custom ExceptionRenderer
+
+A centralized handler has three jobs: logging (including the stack trace), producing a safe, well-formed response for the client, and mapping errors to status codes.
+
+### Preventing Internal Information Leaks
+
+Never include stack traces, SQL, file paths, or environment variables in production error responses. Always verify `DEBUG=False` (Django) and `APP_DEBUG=false` (Laravel) in production. Return only an error code and a correlation ID (request ID) to the client; keep the details in server-side logs.
+
+```typescript
+// NestJS
+// Bad: returns the raw exception message (leaks internal details)
+catch (e) { throw new InternalServerErrorException(e.message); }
+
+// Good: log the details, return only a fixed code and correlation ID to the client
+catch (e) {
+  this.logger.error({ requestId, err: e }, 'order confirmation failed');
+  throw new InternalServerErrorException({ code: 'INTERNAL_ERROR', requestId });
+}
+```
+
+### Retries with Exponential Backoff (External API Calls)
+
+Transient external API failures (timeouts, 429s, 5xx) are worth retrying. 4xx errors (validation failures, etc.) won't succeed on retry, so fail fast instead.
+
+```python
+# Python (conceptual skeleton — in practice, use a library like tenacity)
+# Good: exponential backoff + jitter, with a cap on retry attempts
+import random, time
+
+def call_with_retry(func, max_attempts=4, base=0.5):
+    for attempt in range(1, max_attempts + 1):
+        try:
+            return func()
+        except TransientError:
+            if attempt == max_attempts:
+                raise
+            time.sleep(base * (2 ** (attempt - 1)) + random.uniform(0, 0.1))
+```
+
+Anything you retry must be idempotent. Don't casually retry a non-idempotent POST — only do so if you can attach an idempotency key. Use the silent-failure-hunter subagent to check for swallowed exceptions (`except: pass`, empty `catch` blocks).
+
+## Authentication & Authorization
+
+- Always enforce authorization server-side. Hiding a button or a screen on the frontend is a UX affordance, not a security control — design as if the API can be hit directly.
+- Separate authentication (who you are) from authorization (what you're allowed to do). Even after authentication succeeds, check permission on the target resource for every request.
+- Use each framework's declarative mechanism for role-based authorization: NestJS uses Guards + custom decorators, Django uses `permission_classes` / `@permission_required`, Laravel uses Policies/Gates, Flask uses decorators, CakePHP uses the Authorization plugin.
+- Guard against IDOR (Insecure Direct Object Reference — being able to view another user's resource just by guessing its ID) by including "does the logged-in user own this" as part of the query condition, not as an afterthought check.
+
+```php
+// Laravel
+// Bad: fetching by ID alone (exposes other users' orders)
+$order = Order::findOrFail($id);
+
+// Good: scope the query to the owner, then authorize via a Policy
+$order = $request->user()->orders()->findOrFail($id);
+$this->authorize('view', $order);
+```
+
+```typescript
+// NestJS
+// Good: declare the required role via a decorator and enforce it centrally with a Guard
+@Roles('admin')
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Delete(':id')
+remove(@Param('id') id: string) { ... }
+```
+
+In multi-tenant setups, never accept the tenant ID from the request body — derive it from the authenticated identity and enforce it on every query.
+
+## Rate Limiting
+
+Apply rate limiting to publicly exposed endpoints (login, sign-up, password reset, search, public APIs). This defends against both brute-force attacks and general overload.
+
+- NestJS: `@nestjs/throttler`
+- Django: DRF throttling (`AnonRateThrottle` / `ScopedRateThrottle`), django-ratelimit
+- Flask: Flask-Limiter
+- Laravel: the `throttle` middleware (RateLimiter)
+- CakePHP: a rate-limiting plugin used as middleware
+- Serverless setups: also apply throttling at the API Gateway / WAF layer
+
+In multi-instance deployments, the rate-limit counter must live in a shared store such as Redis — otherwise per-instance counters make the limit effectively meaningless.
+
+## Structured Logging
+
+- Emit logs in a structured format (e.g. JSON) rather than embedding values into message strings, so they're searchable and aggregable as fields.
+- Attach a request ID (correlation ID) to every log line so you can trace one request's full processing path. In NestJS, use AsyncLocalStorage (e.g. nestjs-cls); in Django/Flask, attach it via middleware.
+- For the full house rules on log levels, debug-mode conventions (recording function entry/exit and inputs/outputs), and X-Ray/Sentry integration, consult your repository's own logging conventions/rules document.
+- Include identifying fields (userId, orderId, etc.) as structured fields. Never log personal data or credentials — passwords, tokens, card numbers — under any circumstances.
+
+```typescript
+// NestJS (structured logger such as pino)
+// Bad: no context, not searchable, doesn't say what failed
+this.logger.log('failed');
+
+// Good: correlation ID and target ID as structured fields
+this.logger.warn(
+  { requestId, orderId, reason: 'stock_shortage' },
+  'order confirmation rejected',
+);
+```
+
+How to choose a log level:
+
+- `error`: a failure that needs a human to respond. Should trigger alerts.
+- `warn`: something abnormal but self-recovered, or an expected-in-business failure (succeeded after retry, frequent validation rejections, etc.).
+- `info`: business-event milestones (order confirmed, job completed).
+- `debug`: development-time detail. Disabled by default in production.
+
+Avoid letting your level scheme collapse — e.g. logging normal operation at `error`, or swallowing an exception while logging it at `info`.
+
+## Background Jobs
+
+- Use a durable queue backend: BullMQ (Redis), Celery (Redis / RabbitMQ), Laravel Queue (Redis / SQS / database), SQS, and similar. In-process queues — an in-memory array, chained `setTimeout` calls, or Laravel's `sync` driver in production — are not acceptable; jobs vanish on process restart or deploy.
+- Design jobs to be idempotent. Queues generally guarantee at-least-once delivery, so the same job may run twice — make sure that doesn't corrupt results. Absorb duplicate execution with a "already processed" flag, a uniqueness constraint, or an idempotency key.
+
+```python
+# Celery
+# Bad: running this twice double-charges the customer
+@shared_task
+def charge(order_id):
+    api.charge(amount=get_order(order_id).total)
+
+# Good: a processed-check plus an idempotency key make double execution harmless
+@shared_task(bind=True, max_retries=5)
+def charge(self, order_id):
+    order = get_order(order_id)
+    if order.charged:
+        return
+    api.charge(amount=order.total, idempotency_key=f"charge-{order_id}")
+    order.mark_charged()
+```
+
+- Always design for the failure path: cap the retry count, use exponential backoff, and on exhausting retries, route the job to a dead-letter queue (DLQ) or a failure table (Laravel's `failed_jobs`) with a notification. Never let a failure disappear silently.
+- Pass an ID into the job, not the full entity, and re-fetch the latest state at execution time — this avoids acting on stale data that sat in the queue for a while.
+
+## Related Commands & Subagents
+
+- During the design phase, use `/plan` to nail down the implementation approach before starting.
+- After implementation, request review from `/code-review` and code-reviewer subagents.
+- Use the silent-failure-hunter subagent to check for swallowed exceptions and silently discarded errors.

package/dist/plugin/skills/database-migrations/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: database-migrations
+description: A pattern library for running database migrations safely. Covers universal principles such as backward compatibility, the expand/contract pattern, and rollback design; dangerous operations to avoid in PostgreSQL/MySQL; tool-specific notes for Django, Laravel, TypeORM, and Prisma; and lazy migration for DynamoDB. Use this when planning or reviewing schema changes, data migrations, or migration files.
+---
+
+# Database Migrations — Patterns for Safe DB Migrations
+
+Migrations against a production database tend to be operations you can't undo once they fail.
+This skill collects the principles, dangerous patterns, and tool-specific pointers needed to
+carry out schema changes and data migrations with zero downtime and zero data loss.
+
+## 1. Universal Principles
+
+### 1.1 Backward compatibility: don't break the old code while it's still running
+
+During a deploy there is always a moment where "old code + new schema" or "new code + old schema"
+coexist. With rolling deploys this window can last minutes; even with blue/green deploys there's
+a brief moment of overlap at cutover. A migration must therefore always satisfy both of these:
+
+- The new schema must not break the old code (don't drop or rename columns first)
+- The new code must be able to start up against the old schema (don't assume a new column is
+  already required)
+
+### 1.2 Expand / Contract (the two-phase deploy)
+
+Never make a breaking change in one shot. Always break it down into "add → migrate → remove."
+
+```text
+Phase 1 (Expand)   : Add new columns/tables. Old code simply ignores them, so nothing breaks
+Phase 2 (Migrate)  : Deploy new code that writes to both, or treats the new side as authoritative.
+                      Backfill the data
+Phase 3 (Contract) : Once you've confirmed all code reads only from the new side, drop the old
+                      columns/tables
+```
+
+Leave at least one full deploy cycle between Phase 1 and Phase 3.
+There's no need to rush Phase 3 — you can always delete later, but deleted data doesn't come back.
+
+### 1.3 Rollback-ability
+
+- For every migration, ask: "if the app is rolled back to the previous version right after this
+  migration is applied, does it still work?"
+- A rollback mechanism doesn't have to be a "down" migration. If you follow expand/contract,
+  rolling back just the application *is* the rollback (the schema can safely stay in its
+  forward-compatible state)
+- Destructive operations (DROP, TRUNCATE, narrowing a column's type) can't be undone by a down
+  migration. Take a backup or archive the data to a separate table before running them
+
+### 1.4 Keep schema changes and data migrations separate
+
+Don't mix DDL (schema changes) and DML (data migrations) in the same migration.
+
+- DDL finishes quickly and its lock impact is easy to estimate. DML scales with row count and can
+  run long
+- Mixing them means that if something fails partway through, you're left in the worst possible
+  state: the schema changed but the data is half-migrated
+- Put data migrations in their own migration, or better, a separate batch job or management
+  command
+
+### 1.5 One migration, one purpose
+
+Each file should contain exactly one logical change.
+Cramming "add a column to `users` + add an index to `orders` + drop an unused table" into one file
+makes it hard to reason about state after a partial failure and hard to retry just the failed
+piece. Keeping migrations small makes it easy to pinpoint what failed, retry it, and review it.
+
+## 2. Dangerous Patterns in PostgreSQL / MySQL
+
+### 2.1 Adding a NOT NULL column to a large table
+
+```sql
+-- Dangerous: on PostgreSQL 10 and earlier, or some MySQL configurations, this rewrites
+-- every row and holds a long-lived lock
+ALTER TABLE orders ADD COLUMN status varchar(20) NOT NULL DEFAULT 'pending';
+
+-- Safe, staged migration (PostgreSQL)
+ALTER TABLE orders ADD COLUMN status varchar(20);             -- 1. Add nullable (instant)
+-- 2. Deploy the app so it writes a value on new rows
+-- 3. Backfill existing rows in batches (see 2.4)
+ALTER TABLE orders ALTER COLUMN status SET DEFAULT 'pending'; -- 4. Set the default
+ALTER TABLE orders ALTER COLUMN status SET NOT NULL;          -- 5. Enforce NOT NULL last
+```
+
+On PostgreSQL 11+, `ADD COLUMN` with a constant default is a metadata-only change and is fast,
+but `SET NOT NULL` still requires a full table scan. On PostgreSQL 12+, it's safer to first add
+`CHECK (status IS NOT NULL) NOT VALID` and then run `VALIDATE CONSTRAINT`.
+
+### 2.2 Locking caused by index creation
+
+```sql
+-- Dangerous: a plain CREATE INDEX blocks writes to the table
+CREATE INDEX idx_orders_user_id ON orders (user_id);
+
+-- Safe: use CONCURRENTLY on PostgreSQL (must run outside a transaction)
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders (user_id);
+```
+
+- `CONCURRENTLY` cannot run inside a transaction. In Django this means `atomic = False`; other
+  tools have their own way to disable the per-migration transaction
+- If it fails, an INVALID index is left behind. Drop it with `DROP INDEX CONCURRENTLY` and retry
+- MySQL (InnoDB) usually supports online DDL, but be explicit with
+  `ALTER TABLE ... ALGORITHM=INPLACE, LOCK=NONE` so you get an error (rather than a silent lock)
+  if it's not possible
+- For very large tables on MySQL, consider gh-ost or pt-online-schema-change
+
+### 2.3 Renaming a column or changing its type: do it as a staged migration
+
+`RENAME COLUMN` itself is fast, but as soon as it runs, any old code still referencing the old
+name breaks immediately. Treat a rename as "add a column under a new name."
+
+```text
+1. Add the new-named column (nullable)
+2. Deploy the app so it writes to both columns, but still reads from the old one
+3. Backfill the data by copying old -> new
+4. Deploy the app so it reads from the new column (still writing to both)
+5. Deploy the app so it writes only to the new column
+6. Drop the old column (Contract)
+```
+
+Type changes (e.g. int -> bigint) follow the same recipe by going through a new column of the
+new type. On PostgreSQL, `ALTER TYPE` often rewrites every row under an ACCESS EXCLUSIVE lock.
+The exception is compatible changes, like widening a varchar, which are metadata-only.
+
+### 2.4 Batching backfills
+
+A single bulk UPDATE against existing rows causes long-running transactions, replication lag,
+lock contention, and (on PostgreSQL) VACUUM pressure. Always split it up.
+
+```sql
+-- Dangerous: a single bulk update (tens of millions of rows will blow up locks and WAL/binlog)
+UPDATE orders SET status = 'pending' WHERE status IS NULL;
+
+-- Safe: batch by primary key range
+UPDATE orders SET status = 'pending'
+WHERE id IN (
+    SELECT id FROM orders
+    WHERE status IS NULL
+    ORDER BY id
+    LIMIT 5000          -- tune the batch size based on observed load
+);
+-- Loop this from the application until zero rows match
+```
+
+- Commit each batch in its own transaction, and add a short pause between batches
+- Write it idempotently (the WHERE clause should make it safe to re-run after a partial failure)
+- Check a replica-lag metric inside the loop and pause if it exceeds a threshold
+
+## 3. Tool-Specific Notes
+
+### 3.1 Django migrations
+
+```bash
+# Always add this to CI: it catches model/migration drift (a missing makemigrations)
+python manage.py makemigrations --check --dry-run
+
+# Get in the habit of reviewing the SQL that will actually run before applying it
+python manage.py sqlmigrate shop 0042
+```
+
+```python
+from django.db import migrations
+
+def forwards(apps, schema_editor):
+    # Always use apps.get_model. Importing the model directly will break this
+    # migration when the model changes in the future
+    Order = apps.get_model("shop", "Order")
+    while True:
+        ids = list(
+            Order.objects.filter(status__isnull=True).values_list("id", flat=True)[:5000]
+        )
+        if not ids:
+            break
+        Order.objects.filter(id__in=ids).update(status="pending")
+
+class Migration(migrations.Migration):
+    atomic = False  # Disable the per-migration transaction for bulk data work or
+                     # CREATE INDEX CONCURRENTLY
+    dependencies = [("shop", "0041_add_status")]
+    operations = [
+        # Always specify reverse. Even if no reverse action is needed, make the noop
+        # explicit rather than leaving the migration irreversible
+        migrations.RunPython(forwards, migrations.RunPython.noop),
+    ]
+```
+
+- Leaving `reverse` unspecified on `RunPython` makes that migration irreversible
+- For adding indexes on PostgreSQL, use `AddIndexConcurrently`
+  (`django.contrib.postgres.operations`) together with `atomic = False`
+- Squash migrations periodically to keep fresh-environment setup time and the dependency graph
+  manageable
+
+### 3.2 Laravel migrations
+
+```php
+public function up(): void
+{
+    Schema::table('orders', function (Blueprint $table) {
+        // Add as nullable; enforce NOT NULL in a separate migration
+        $table->string('status', 20)->nullable();
+    });
+}
+
+public function down(): void
+{
+    Schema::table('orders', function (Blueprint $table) {
+        $table->dropColumn('status');
+    });
+}
+```
+
+- Always write `down()` for local-dev convenience, but don't rely on it as your production
+  rollback mechanism. In production, handle rollback via expand/contract plus rolling back the
+  application, not `migrate:rollback`
+- MySQL implicitly commits DDL statements, so packing multiple DDL statements into one file can
+  leave things half-applied after a mid-migration failure. Stick to one migration, one purpose
+- `php artisan migrate --pretend` lets you preview the SQL before it runs
+
+### 3.3 TypeORM / Prisma
+
+- TypeORM: never use `synchronize: true` in production (it rewrites the schema implicitly).
+  Always eyeball the SQL that `migration:generate` produces to make sure it doesn't contain an
+  unintended DROP. Running migrations explicitly from the deploy pipeline via `migration:run` is
+  easier to control than auto-running them at app startup (`migrationsRun`)
+- Prisma: use only `prisma migrate deploy` for production. `migrate dev` is for local development
+  only and can create/reset a shadow database. Don't use `prisma db push` in production either,
+  since it doesn't leave a migration history. The generated `migration.sql` file can be hand
+  edited, so make adjustments like switching `CREATE INDEX` to `CONCURRENTLY` directly in that
+  file
+- For both tools, "auto-generated" does not mean "safe." A rename being generated as DROP + ADD,
+  losing data in the process, is a classic mistake with either tool
+
+## 4. DynamoDB
+
+Being schemaless doesn't mean migrations go away — it just means the schema has moved into the
+application code, and the application is now responsible for compatibility.
+
+### 4.1 Lazy migration (migrate on read)
+
+Rewriting every item in bulk is expensive and risky, so convert items to the new shape lazily,
+as they're read.
+
+```typescript
+// Give each item a version attribute and convert it incrementally on read
+function migrateItem(item: Record<string, any>): Order {
+  const version = item.schemaVersion ?? 1;
+  if (version < 2) {
+    // v1 -> v2: split fullName into firstName / lastName
+    const [firstName, ...rest] = (item.fullName ?? '').split(' ');
+    item.firstName = firstName;
+    item.lastName = rest.join(' ');
+    item.schemaVersion = 2;
+  }
+  return item as Order;
+}
+```
+
+- Always write items back in the latest shape, along with an updated `schemaVersion`
+- Your read-path conversion function needs to keep supporting conversion from every past version.
+  If you want to drop support for old versions, run a one-time background scan-and-migrate job
+  first to bring everything current
+- If you do run a bulk migration, use a segmented parallel Scan with rate limiting so you don't
+  eat into your write capacity
+
+### 4.2 Operating GSI additions
+
+- Adding a GSI can be done online, but the backfill takes time, and queries against the index
+  before it finishes will return incomplete results. Wait until the index reports ACTIVE before
+  cutting the application over to it
+- In other words, a GSI addition needs the same two-phase deploy as an RDBMS expand/contract:
+  add -> wait for backfill -> cut over the code
+- A GSI's key attributes can't be changed after creation. To change them, add a new GSI and drop
+  the old one once you've cut over
+
+### 4.3 Key design changes are hard
+
+- Partition keys and sort keys can't be changed once a table is created. Changing them really
+  means "create a new table, copy all the data, and cut over"
+- In a CQRS setup, if you design things so the read model (query-side table) can be rebuilt from
+  the command-side events, then a key-design change on the query side reduces to a re-projection
+- Where a migration truly is needed, set up dual writes via DynamoDB Streams, and cut reads over
+  to the new table once the copy is complete
+
+## 5. Pre-Execution Safety Checklist
+
+1. Will the previous version of the application still work after this schema change (backward
+   compatibility)?
+2. If this includes a breaking change (DROP / RENAME / narrowing a type), has it been broken down
+   into expand/contract?
+3. Have you checked the row count and size of the target table, and estimated the runtime against
+   a production-scale data volume?
+4. Have you identified what kind of lock will be taken, and how lock waits will affect the
+   application?
+5. Have you set `lock_timeout` / `statement_timeout` (or `lock_wait_timeout` on MySQL)?
+6. Is the data migration batched and idempotent, with a documented recovery procedure for a
+   partial failure?
+7. Have you documented the rollback procedure (one that doesn't depend on a down migration)?
+8. Have you verified that a backup / snapshot / PITR is in place right before running it?
+9. Have you rehearsed this against production-scale data in staging?
+10. Have you picked a low-traffic execution window and lined up monitoring (replica lag, locks,
+    error rate)?
+
+## 6. Anti-patterns
+
+| Anti-pattern | What happens | Do this instead |
+| --- | --- | --- |
+| Releasing a column drop and the code change together | Old code crashes mid-rollout | Do the Contract step in a separate release, after the rollout is fully complete |
+| Running `RENAME COLUMN` in one shot | Old code errors out immediately | Add a new column, dual-write, then cut over in stages |
+| Bulk UPDATE against a huge table | Long transactions, locking, replica lag | Batch by primary-key range, with pauses |
+| `CREATE INDEX CONCURRENTLY` inside a transaction | Errors out, or silently runs as a regular, locking `CREATE INDEX` | Disable the transaction and run it standalone |
+| Mixing DDL and DML in one migration | A failure leaves things half-applied | Separate schema changes from data migrations |
+| Treating a down migration as your production rollback plan | Data loss, or an unverified down that itself fails | Preserve forward compatibility and roll back via the application instead |
+| Applying ORM-generated SQL without review | A rename becomes DROP + ADD and data is lost | Always eyeball the generated SQL |
+| Using `synchronize: true` / `db push` in production | Implicit schema changes with no migration history | Change the schema only via migration files |
+| Rewriting all DynamoDB items in one pass | Production impact from exhausted capacity | Use lazy migration, or a rate-limited bulk migration |
+| Importing application models directly inside a migration | A future model change breaks past migrations | Use a historical model (e.g. Django's `apps.get_model`) |
+
+## 7. Related Workflow
+
+- Before starting a large schema change, use `/plan` to work out the breakdown into
+  expand/contract steps and the release ordering
+- Send changes that include migrations to `/code-review`
+- For Django-specific migration safety (transaction control, `RunPython` reverse functions,
+  lock-holding operations), have the `django-reviewer` subagent take a close look