oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-db/resources/anti-patterns.md

@@ -0,0 +1,177 @@
+# DB Agent - Anti-Pattern Review Guide
+
+Use this file for DB review, schema/query critique, remediation, or changes involving business logic in DB objects or ORM hooks. Review the affected scope; a query/index task does not require a database-wide inventory or rewrite.
+
+## 1. ISO 27001 / 27002 / 22301-Oriented Suggestions
+
+When any of the following are weak or absent, recommend improvements explicitly:
+
+- access control and least privilege
+- encryption in transit and at rest
+- audit logging for privileged or sensitive data changes
+- backup, restore drill, and retention evidence
+- data classification and PII handling
+- schema change management and migration traceability
+- secure credential handling
+- deletion and archive controls for cold data
+- privileged access review and segregation of duties
+- secure configuration baselines and hardening guidance
+- business continuity planning assumptions for critical databases
+- recovery objectives such as RTO / RPO and restore evidence
+- failover, redundancy, and backup dependency visibility
+
+## 2. Logical Design
+
+- **CSV in one column**
+  - Smell: comma-separated IDs/tags/statuses stored in `VARCHAR`
+  - Fix: separate dependent table or junction table for many-to-many
+- **Naive tree**
+  - Smell: `parent_id` only, but complex subtree queries and moves are required
+  - Fix: choose the tree model that matches the workload and relationship semantics
+- **Surrogate-key obsession**
+  - Smell: every table gets generic `id` without regard to natural/composite identity
+  - Fix: use natural key or composite key when it models the domain better; prefer descriptive PK names like `bug_id`
+- **Missing foreign keys**
+  - Smell: referential integrity delegated to application code
+  - Fix: add FK constraints and let the DB reject invalid references
+- **EAV**
+  - Smell: generic `entity_id`, `attr_name`, `attr_value`
+  - Fix: use subtype modeling, JSON only when true schema flexibility is required
+- **Polymorphic association**
+  - Smell: one FK-like column can point to multiple parent tables
+  - Fix: simplify relationships, use junction tables, or introduce a shared supertype
+- **Repeated columns for multi-value attributes**
+  - Smell: `tag1`, `tag2`, `tag3`
+  - Fix: store one value per row in a dependent table
+- **Metadata as schema**
+  - Smell: table names or column names encode data values such as year or tenant
+  - Fix: use partitioning, proper normalization, or vertical split
+
+## 3. Physical Design
+
+- **Floating-point money**
+  - Smell: `FLOAT/REAL/DOUBLE` for currency or exact quantities
+  - Fix: use `NUMERIC/DECIMAL`
+- **Hard-coded enum in schema without governance**
+  - Smell: volatile code sets trapped inside enum/check definitions
+  - Fix: use reference tables when values are expected to evolve
+- **Ghost file**
+  - Smell: DB stores only file path while lifecycle, backup, authorization, and restore are unmanaged
+  - Fix: use BLOB/object storage only with clear lifecycle, permissions, and backup/restore design
+- **Index shotgun**
+  - Smell: indexes created by guesswork or duplicated heavily
+  - Fix: MENTOR the indexes:
+    - Measure
+    - Explain
+    - Nominate
+    - Test
+    - Optimize
+    - Rebuild
+
+## 4. Query Design
+
+- **NULL misuse**
+  - Smell: NULL treated like a normal value or fake defaults used instead of NULL
+  - Fix: use `IS NULL`, `IS NOT NULL`, `COALESCE`, and proper nullability semantics
+- **Ambiguous grouping**
+  - Smell: non-grouped columns selected beside aggregates
+  - Fix: obey the single-value rule or rewrite with proper subqueries/window logic
+- **Random sort**
+  - Smell: `ORDER BY RAND()` on large tables
+  - Fix: choose a sampling strategy that avoids full random sort
+- **Poor-man's search engine**
+  - Smell: broad `%keyword%` or regex search on large text
+  - Fix: use full-text indexing or a dedicated search engine
+- **Spaghetti query**
+  - Smell: forcing every rule into one giant SQL statement
+  - Fix: split into stages or multiple queries when it improves correctness and maintainability
+- **Implicit columns**
+  - Smell: `SELECT *` in production paths
+  - Fix: list required columns explicitly
+
+## 5. Application Integration
+
+### Application Ownership Policy
+
+Strongly recommend managing business decisions, workflow orchestration, and external side effects explicitly in application domain/services and jobs. Apply this recommendation to **new and existing** implementations, including triggers, stored procedures, stored functions, views, DB events/schedulers, and ORM hooks/entity listeners. This is a design default, not a blanket ban on those mechanisms.
+
+For each affected existing implementation, identify its callers and writers, explain the risk, recommend a concrete replacement, and state the transition priority. Existing usage or convention alone is not a reason to retain it. If retention is justified, record the application alternative, the technical reason (such as atomicity across writers, measured performance, or audit requirements), and the relevant tests, privileges, deployment, and recovery approach. Recommend a staged transition when replacement is appropriate; implementation remains within the authorized scope.
+
+### Patterns to Improve
+
+| Pattern and failure mechanism | Strongly recommended alternative |
+| --- | --- |
+| Business policy in triggers, procedures, functions, views, or large `CASE` expressions: pricing, fees, eligibility, visibility, and approval rules become duplicated or tied to DB deployments | Give the policy an application owner and tests; version changing policies with effective dates and record the version/inputs used for decisions that must be reproduced |
+| Implicit workflow: setting a status or saving an entity silently triggers payment, approval, shipment, or chained writes | Use explicit commands, validated state transitions, and service orchestration; moving the same hidden behavior into ORM hooks is not an improvement |
+| External I/O inside DB execution, or a DB commit followed by an independent broker/API write: failures leave partial effects that rollback cannot undo | Record the integration event in an outbox in the same transaction as business data; publish through a worker with idempotency and bounded retry, and define compensation for partial external success |
+| Business scheduling in DB events/jobs without execution ownership: settlement, expiry, and notifications lack retry limits, checkpoints, or failure visibility | Manage execution in an application job/workflow with observable runs and recovery; validate deadlines at action time rather than trusting a delayed expiry batch |
+| Trigger-driven cache/search synchronization or cross-system projections without replay/reconciliation | Use explicit events or CDC with consumer deduplication, ordering requirements, lag monitoring, replay, and reconciliation |
+| Policy bypass through multiple writers or procedures that modify another service's tables | Identify API, batch, admin, import, and direct SQL writers; align write permissions and policy enforcement, and use the owning service's API/events across service boundaries |
+| Cascading deletion of independently owned objects or trigger-driven soft delete without retention/restore rules | Manage deletion intent, authorization, retention, and restoration in the application; define explicit coordination across ownership boundaries |
+| Business authorization and audit context hidden in DB session state or routines | Give business authorization and action intent an application owner; propagate verified actor/tenant context and record decision reasons, while preserving DB enforcement and DB change/access audit |
+
+### Database Responsibilities to Preserve
+
+- Keep declarative integrity (`PK`, `FK`, `UNIQUE`, `CHECK`, `NOT NULL`, and exclusion constraints where supported), atomic conditional updates, transaction boundaries, isolation, and locking. Application prechecks alone cannot enforce invariants under concurrent or independent writes.
+- Preserve RLS and DB privileges where they enforce access restrictions; RLS can be the primary enforcement point. Verify the connection roles, bypass privileges, and actor/tenant context rather than replacing RLS with application filtering.
+- Keep DB access/change audit where required. Application business audit does not cover every direct SQL, administrator, or batch change. Audit triggers can be justified, but their coverage and privileged bypass limits must be explicit.
+- `ON DELETE CASCADE` can be appropriate for dependent components with the same lifecycle. Flag cascades across independent ownership or retention boundaries, rather than treating every cascade as an anti-pattern.
+- Keep efficient joins, aggregates, pure SQL functions/views, generated values, and set-based bulk operations in the DB where appropriate. Application ownership of a job does not require fetching all rows into an application loop. DB-local summaries or routines may be retained with correctness and performance evidence.
+- Backup, replication, vacuum/statistics, partition maintenance, and storage TTL remain database operations. Separate physical cleanup from business expiry and retention decisions.
+- CDC transports committed changes; it does not automatically supply the business intent of a domain event. An application can write an outbox and use CDC to publish it. Neither approach removes the need to handle duplicates, ordering, or consumer recovery.
+
+For an accepted transition, use `resources/migration-playbook.md` §Moving Business Logic into the Application. Preserve all writers and invariants, and prevent the old and new paths from executing the same external effect twice.
+
+### Other Integration Anti-Patterns
+
+- **Readable passwords**
+  - Smell: plaintext or reversibly encrypted passwords
+  - Fix: salted one-way hash, secure transport, no password recovery by disclosure
+- **SQL injection**
+  - Smell: unchecked input concatenated into SQL
+  - Fix: parameterized queries, allowlists for dynamic clauses, code review
+- **Surrogate-key gap paranoia**
+  - Smell: trying to fill deleted ID gaps
+  - Fix: treat surrogate keys as identifiers, not row numbers
+- **Ignoring DB return values and executed SQL**
+  - Smell: no error handling or no visibility into actual SQL
+  - Fix: inspect execution results, logs, and emitted SQL
+- **SQL exempt from engineering discipline**
+  - Smell: no version control, no tests, no review, no documentation
+  - Fix: treat DB artifacts like code
+- **Active Record leakage**
+  - Smell: controllers calling persistence methods directly
+  - Fix: keep service/repository boundaries and avoid mixing UI flow with DB access
+
+## 6. Vector Retrieval / RAG
+
+- **Treating vector DB as a drop-in search replacement**
+  - Smell: lexical search removed entirely after adding embeddings
+  - Fix: default to hybrid retrieval; combine keyword/BM25, metadata filters, ANN, and reranking
+- **Embedding everything without a versioning strategy**
+  - Smell: multiple models/dimensions/chunk rules with no metadata or migration plan
+  - Fix: version embeddings like schema, store model/config metadata, and support rolling re-embedding
+- **Ignoring chunking strategy**
+  - Smell: fixed-size chunks and naive splitting regardless of document structure
+  - Fix: use document-aware chunking, overlap, and hierarchical structure where needed
+- **Blind ANN defaults**
+  - Smell: HNSW/IVF/PQ defaults used without recall-latency benchmarking
+  - Fix: benchmark real workloads and tune ANN parameters deliberately
+- **Assuming metadata filtering scales for free**
+  - Smell: high-cardinality filters piled onto vector search with no partition strategy
+  - Fix: design pre-segmentation, partitioned indexes, or tenant-specific collections where justified
+- **Unplanned real-time writes**
+  - Smell: continuous inserts degrade recall and latency over time
+  - Fix: design buffers, compaction, tiered indexing, and ingestion/search separation
+- **Storing raw documents in vector DB**
+  - Smell: vector DB becomes source of truth for full documents
+  - Fix: keep canonical docs in object store or primary DB and store references in vector DB
+- **No retrieval observability**
+  - Smell: only infra metrics exist; no recall or semantic drift monitoring
+  - Fix: add golden queries, offline evaluation, drift tracking, and token-waste monitoring
+- **Over-trusting similarity scores**
+  - Smell: one cosine threshold is treated as universally meaningful
+  - Fix: calibrate per domain/model and use reranking for precision-sensitive cases
+- **Believing vector DB equals RAG architecture**
+  - Smell: only index layer is optimized while chunking, orchestration, and feedback loop are ignored
+  - Fix: treat retrieval as a pipeline, not a single database decision

package/skills/oma-db/resources/checklist.md

@@ -0,0 +1,67 @@
+# DB Agent - Self-Verification Checklist
+
+Run through every item before submitting your work.
+
+## Modeling
+- [ ] DB type selection justified from workload, not preference
+- [ ] Relational models normalized to at least 3NF, or denormalization explicitly justified
+- [ ] NoSQL models aligned to concrete access patterns and aggregate boundaries
+- [ ] Graph model used only where variable-depth traversal or relationship-pattern queries dominate; relational adjacency preferred for shallow fixed-depth cases
+- [ ] Vector retrieval is used only where semantic similarity is actually required
+- [ ] Keys, cardinality, and ownership clearly defined
+- [ ] No obvious anti-patterns remain: CSV-in-column, repeated columns, EAV, polymorphic FK, missing FK
+
+## Schema Documentation
+- [ ] External schema documented
+- [ ] Conceptual schema documented
+- [ ] Internal schema documented
+- [ ] Naming standards and field definitions documented
+- [ ] Glossary / terminology dictionary updated
+
+## Integrity & Concurrency
+- [ ] Entity, domain, referential, and business-rule integrity addressed
+- [ ] Transaction boundaries documented
+- [ ] Isolation level selected for critical flows
+- [ ] Locking / optimistic concurrency strategy documented
+- [ ] Transparency assumptions called out when using distributed systems
+
+## Application Ownership (Affected Scope)
+- [ ] Affected triggers, stored procedures/functions, views, DB jobs, and ORM hooks reviewed for business policy, implicit workflows, and external side effects
+- [ ] New and existing findings receive a strong application ownership recommendation with a concrete alternative and transition priority; retained implementations have technical evidence beyond existing convention
+- [ ] Proposed design preserves DB integrity, concurrency, RLS/privileges, audit coverage, justified dependent cascades, and efficient set-based processing
+- [ ] Where relevant, policy versions/decision context, action-time expiry checks, and all API/batch/admin/import/direct SQL writers are addressed
+- [ ] Integration events are committed atomically with business data when needed; CDC intent/coverage, idempotency, ordering, bounded retry, replay, and compensation are explicit
+- [ ] Planned transitions verify policy behavior and writer coverage, use one owner per side effect, and define rollback without lost or duplicate effects
+
+## Performance & Operations
+- [ ] Indexes match hot queries and join/filter patterns
+- [ ] Partitioning / sharding strategy justified if introduced
+- [ ] Hot vs cold data separation considered
+- [ ] Full and incremental backup strategy documented
+- [ ] Restore test or recovery validation approach documented
+- [ ] Query anti-patterns reviewed: `SELECT *`, random sort, ambiguous grouping, full wildcard search without proper tooling
+- [ ] Slow-query fixes verified with before/after execution plans on production-like data (estimate vs actual rows checked)
+- [ ] Schema changes on live tables follow expand-contract with lock-aware DDL, lock timeouts, and batched, resumable backfill
+- [ ] Destructive (contract) steps deferred to a separate deploy after a soak window, with a final backup taken first
+
+## Vector Retrieval
+- [ ] Vector DB is not being used as the canonical document store
+- [ ] Hybrid retrieval considered where exact match, explainability, or compliance filtering matter
+- [ ] Embedding model, dimension, normalization, chunking, and version metadata documented
+- [ ] Re-embedding / re-index migration plan exists for model or chunking changes
+- [ ] ANN index choice and tuning parameters benchmarked on production-like data
+- [ ] Metadata filtering behavior and high-cardinality filter impact understood
+- [ ] Similarity score thresholds calibrated per domain or reranking added for precision-critical paths
+- [ ] Retrieval observability defined: golden queries, recall drift, semantic drift, token waste
+
+## Capacity
+- [ ] Capacity sheet updated by object
+- [ ] Tablespace/storage estimate updated
+- [ ] Disk estimate includes online, batch, backup, and growth assumptions
+- [ ] Data type choices reviewed for storage efficiency
+
+## Delivery
+- [ ] Assumptions, tradeoffs, and risks are explicit
+- [ ] Migration impact or rollout steps included when schema changes are proposed
+- [ ] ISO 27001 / 27002-friendly suggestions included where design affects access control, logging, encryption, backup, recovery, or change management
+- [ ] ISO 22301-friendly suggestions included where design affects resilience, failover, restore testing, RTO, or RPO

package/skills/oma-db/resources/document-templates.md

@@ -0,0 +1,107 @@
+# DB Agent - Deliverable Templates
+
+Use this structure when the user asks for modeling or DB architecture outputs.
+
+## 1. Decision Summary
+
+```md
+## Database Decision Summary
+- Workload type:
+- Recommended engine/model:
+- Reason:
+- Consistency target:
+- Availability target:
+- Retention target:
+- RPO / RTO:
+```
+
+## 2. Schema Documentation
+
+```md
+## External Schema
+- Consumer / view:
+- Required fields:
+- Access pattern:
+
+## Conceptual Schema
+- Entity / aggregate:
+- Description:
+- Relationships:
+- Cardinality:
+
+## Internal Schema
+- Object name:
+- Type: table / collection / index / partition
+- Primary key / shard key:
+- Constraints:
+- Access path:
+- Storage / tablespace:
+```
+
+## 3. Data Standards
+
+```md
+| Standard Item | Value |
+| --- | --- |
+| Naming convention | |
+| Definition rule | |
+| Data type / format rule | |
+| Allowed value rule | |
+| Nullability rule | |
+| Default value rule | |
+```
+
+## 4. Glossary
+
+```md
+| Term | Definition | Synonym / Forbidden Term | Owner |
+| --- | --- | --- | --- |
+```
+
+## 5. Capacity Estimation
+
+```md
+| Object | Daily Txn | Online Workload | Batch Workload | Row / Doc Size | Growth | Retention | Primary Storage | Backup Storage |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+```
+
+Add these summary sections after the table:
+- tablespace/storage allocation
+- disk total with growth buffer
+- hot vs cold data split
+- backup type and cadence
+
+## 6. Concurrency & Integrity
+
+```md
+## Integrity
+- Entity integrity:
+- Domain integrity:
+- Referential integrity:
+- Business-rule integrity:
+
+## Concurrency
+- Critical transaction:
+- Isolation level:
+- Locking method:
+- Retry / idempotency strategy:
+```
+
+## 7. Vector Retrieval Design
+
+```md
+## Vector Retrieval Design
+- Use case:
+- Why vector retrieval is needed:
+- Why lexical search alone is insufficient:
+- Hybrid retrieval approach:
+- Canonical document store:
+- Vector store contents:
+- Embedding model / dimension / normalization:
+- Chunking policy / overlap:
+- ANN index type / key tuning params:
+- Metadata filtering strategy:
+- Reranking strategy:
+- Re-embedding migration plan:
+- Retrieval evaluation metrics:
+```

package/skills/oma-db/resources/error-playbook.md

@@ -0,0 +1,50 @@
+# DB Agent - Error Playbook
+
+## Symptom: Relational model is breaking 3NF everywhere
+- Re-check whether reporting columns, derived values, and snapshots are being mixed into OLTP tables
+- Split transactional source-of-truth from read models or marts
+- Keep denormalization only where query cost justifies it
+
+## Symptom: NoSQL model keeps requiring cross-document joins
+- Re-evaluate aggregate boundaries and access patterns
+- If strong cross-entity consistency dominates, switch recommendation toward relational storage
+
+## Symptom: Isolation level is unclear
+- Start from anomaly prevention required by the business flow
+- Document what must be prevented: dirty read, non-repeatable read, phantom, lost update
+- Choose the lowest level that still blocks unacceptable anomalies
+
+## Symptom: Capacity estimate is unreliable
+- Separate online traffic, batch traffic, retention, and backup retention
+- Estimate by object first, then aggregate to tablespace and disk totals
+- Add growth and reindex/maintenance headroom
+
+## Symptom: Backup plan exists but restore confidence is low
+- Add restore drill frequency
+- Define sample recovery scenarios and max tolerable data loss
+- Distinguish snapshot/full backup from incremental/log-based recovery
+
+## Symptom: Deadlocks in production
+- Read the engine's deadlock log to identify the two lock cycles, not just the victim
+- Enforce consistent lock ordering: all transactions touch shared tables/rows in the same order
+- Shorten transactions: move reads, external calls, and computation outside the transaction boundary
+- Index foreign keys involved in the cycle; unindexed FK checks escalate to scans and widen lock footprints
+- Add bounded retry with backoff at the application layer for the surviving unavoidable cases
+
+## Symptom: Replication lag growing
+- Look for long-running transactions on the primary holding back apply/vacuum
+- Check for unbatched bulk writes (backfills, cascading deletes) and throttle them per `resources/migration-playbook.md`
+- Verify large-table DML has supporting indexes on the replica side
+- If reads require read-your-writes, route those sessions to the primary or gate on replica LSN/GTID instead of hoping lag stays low
+
+## Symptom: Connection pool exhausted
+- Compare app pool size x instance count against the DB's max connections; oversubscription starves everyone
+- Hunt leaked connections: sessions idle-in-transaction, missing release on error paths
+- Scope sessions to the request/transaction, never to long-lived objects (see backend rule: no shared mutable ORM sessions)
+- Front high-instance-count deployments with a server-side pooler (e.g. pgbouncer) instead of raising max connections
+
+## Symptom: Migration failed midway
+- Determine what actually applied: transactional DDL engines roll back cleanly; others leave partial state to inspect object-by-object
+- Make migration steps idempotent (`IF NOT EXISTS`, guarded DML) so re-running is safe
+- Resume batched backfills from their checkpoint rather than restarting from zero
+- If the failure was a lock timeout, that is the playbook working: retry at a quieter window per `resources/migration-playbook.md`

package/skills/oma-db/resources/examples.md

@@ -0,0 +1,170 @@
+# DB Agent - Examples
+
+## Example 1: Relational Order Management
+
+**Input**: "Design the database for ordering, payment, shipment, and refund flows."
+
+**Output**:
+```md
+## Model Choice
+- PostgreSQL chosen for strong integrity, cross-entity transactions, and reporting joins
+
+## Conceptual Schema
+- Customer 1:N Order
+- Order 1:N OrderItem
+- Order 1:N Payment
+- Order 1:N Shipment
+- Order 1:N Refund
+
+## Internal Schema
+- orders(id PK, customer_id FK, status, ordered_at, total_amount, currency_code)
+- order_items(id PK, order_id FK, product_id FK, qty, unit_price, line_amount)
+- payments(id PK, order_id FK, payment_method_code, status, approved_at, amount)
+- shipments(id PK, order_id FK, warehouse_id FK, status, shipped_at)
+- refunds(id PK, payment_id FK, reason_code, refunded_at, amount)
+
+## Integrity / Concurrency
+- 3NF satisfied
+- FKs enforce referential integrity
+- Unique(order_id, product_id) for line uniqueness
+- Payment capture uses READ COMMITTED with idempotency key
+- Inventory reservation uses SELECT ... FOR UPDATE
+
+## Operations
+- Hot data: last 12 months in primary partition
+- Cold data: monthly archive partitions after 12 months
+- Daily full backup + 15-minute incremental/WAL archiving
+```
+
+## Example 2: NoSQL Activity Feed
+
+**Input**: "Model a high-write social feed with fan-out reads."
+
+**Output**:
+```md
+## Model Choice
+- NoSQL chosen because feed reads follow aggregate access by user timeline and tolerate eventual consistency
+
+## Conceptual Schema
+- User aggregate
+- Post aggregate
+- TimelineEntry aggregate
+
+## Internal Schema
+- users collection keyed by user_id
+- posts collection keyed by post_id
+- timelines collection keyed by owner_user_id + created_at
+
+## Consistency / BASE
+- Timeline fan-out is eventually consistent
+- Post delete creates compensating cleanup event
+- Source-of-truth post document retained separately from denormalized timeline entry
+
+## Optimization
+- Partition key: owner_user_id
+- TTL on ephemeral recommendation cache
+- Cold feed archive after 180 days
+- Nightly full snapshot + hourly incremental backup
+```
+
+## Example 3: Data Standards & Capacity Update
+
+**Input**: "Add subscription billing and keep the glossary and sizing docs current."
+
+**Output**:
+```md
+## Data Standards
+| Name | Definition | Format | Rule |
+| --- | --- | --- | --- |
+| subscription_status_code | Subscription lifecycle state | VARCHAR(20) | ACTIVE, PAUSED, CANCELED only |
+| billing_cycle_day | Day of month for billing | SMALLINT | 1-28 only |
+
+## Glossary Additions
+- Subscription: recurring billing agreement between customer and service
+- Invoice: billable statement generated for a subscription cycle
+
+## Capacity Update
+- subscriptions: 1.2M rows / year
+- invoices: 14.4M rows / year
+- payments: 16M rows / year
+- Estimated primary storage: 180 GB / year
+- Backup storage multiplier: 2.5x including retention
+```
+
+## Example 4: Enterprise RAG Retrieval
+
+**Input**: "Design a policy search platform using a vector DB for enterprise RAG."
+
+**Output**:
+```md
+## Model Choice
+- PostgreSQL remains source of truth for document metadata and lifecycle
+- Object storage holds canonical documents
+- Vector DB is used only as semantic retrieval index
+
+## Retrieval Architecture
+- Hybrid retrieval = BM25 + ANN + metadata filter + cross-encoder rerank
+- Filters applied for tenant_id, region, policy_type, effective_date
+- Exact compliance terms still supported by lexical search
+
+## Embedding Governance
+- embedding_model: text-embedding-3-large
+- embedding_version: v2026_03_policy_chunks_v2
+- chunking: heading-aware, 350-600 tokens, 80-token overlap
+- Shadow index used during re-embedding migration
+
+## ANN / Operations
+- HNSW selected after recall-latency benchmark
+- search cluster separated from ingestion cluster
+- Hot vectors: last 90 days of updated policies
+- Cold vectors: older embeddings compacted to lower-cost tier
+
+## Observability
+- Golden query set maintained for recall regression
+- Similarity score distribution monitored by policy domain
+- Prompt token waste tracked for bad retrieval
+```
+
+## Example 5: Anti-Pattern Remediation on a Live Table
+
+**Input**: "Our `products` table stores tags as a comma-separated column, prices as FLOAT, and category lookups are slow. Fix it without downtime."
+
+**Output**:
+```md
+## Findings (anti-pattern review)
+- CSV-in-column: `products.tags VARCHAR` holds comma-separated tags -> junction table
+- Floating-point money: `products.price FLOAT` -> NUMERIC(12,2)
+- Slow category lookup: Seq Scan confirmed via EXPLAIN (ANALYZE); estimated 200 rows vs actual 1.8M -> stale stats + missing composite index
+
+## Remediation Plan (expand-contract, four deploys)
+1. Expand (additive only)
+   - CREATE TABLE product_tags(product_id FK, tag_id FK, PRIMARY KEY(product_id, tag_id))
+   - ALTER TABLE products ADD COLUMN price_amount NUMERIC(12,2) (nullable)
+   - CREATE INDEX CONCURRENTLY idx_products_category_active ON products(category_id, is_active)
+2. Migrate (dual-write + backfill)
+   - App writes tags to both column and junction table; price to both columns
+   - Backfill in 10k-row PK batches with checkpointing; replication lag watched, throttled at threshold
+   - Parity: row-count + sampled checksum comparison recorded
+3. Switch (reads behind flag)
+   - Reads flip to product_tags / price_amount; old paths kept for rollback; 1-week soak
+4. Contract (separate deploy, after soak + final backup)
+   - Drop products.tags and products.price; VALIDATE NOT NULL on price_amount via CHECK NOT VALID first
+
+## Verification
+- ANALYZE products; EXPLAIN (ANALYZE, BUFFERS) before/after recorded: Seq Scan -> Index Scan, p95 420ms -> 6ms
+- lock_timeout = '2s' + retry on every DDL; no COPY-algorithm DDL on the hot table
+```
+
+## Example 6: New Order Approval Flow
+
+**Input**: "Add a trigger that approves orders, charges the card, and sends email when status becomes READY."
+
+**Recommendation**: Strongly recommend an explicit application command for approval and a versioned eligibility policy. Persist the validated transition and an outbox event in one transaction; use a worker for payment/email with idempotency, bounded retry, and a defined recovery path for partial success. Keep FK/UNIQUE/CHECK constraints and concurrency protection in the DB. A status update or ORM save hook must not silently become the workflow entry point.
+
+## Example 7: Existing Procedure and Expiry Job
+
+**Input**: "The existing settlement procedure calculates fees, and a DB job marks subscriptions expired. Keep using them because that is our convention."
+
+**Recommendation**: Strongly recommend application ownership of fee policy and business job execution; existing convention alone is not retention evidence. First inspect API, batch, admin, and direct SQL writers. Version fee policies and record which version produced a settlement; validate `expires_at` when an action occurs rather than relying on the expiry job having run.
+
+**Transition**: Compare old/new decisions without charging or notifying twice, coordinate one execution owner across old app instances and DB routines, and preserve a tested rollback path during the soak window. Keep DB constraints, atomic updates, RLS, change audit, and efficient SQL aggregation. An audit trigger that records every affected writer may remain with documented coverage and bypass limits. Retain a DB calculation routine only with a concrete reason, such as measured data-local processing cost, plus correctness/concurrency tests and deployment/recovery evidence.