@jetrabbits/agentic 0.0.1

package/areas/software/backend/workflows/test-feature.md

@@ -0,0 +1,67 @@
+---
+name: test-feature
+type: workflow
+trigger: /test-feature
+description: Expand backend test coverage with risk-based scenario design and stable CI integration.
+inputs:
+  - feature_scope
+  - acceptance_criteria
+outputs:
+  - comprehensive_test_suite
+  - quality_report
+roles:
+  - qa
+  - developer
+  - team-lead
+execution:
+  initiator: qa
+related-rules:
+  - testing.md
+  - architecture.md
+uses-skills:
+  - troubleshooting
+  - database-modeling
+quality-gates:
+  - critical paths and failure paths covered
+  - all tests stable across 3+ consecutive CI runs
+  - coverage meets project threshold
+---
+
+## Steps
+
+### 1. Coverage Gap Analysis — `@qa`
+- **Input:** feature scope + acceptance criteria + current test suite
+- **Actions:** map acceptance criteria to existing tests; identify untested critical paths, failure paths, and edge cases; prioritize gaps by business risk (data integrity > performance > UX)
+- **Output:** `test_coverage_gaps.md` — gap list with risk classification per gap
+- **Done when:** gap list reviewed and prioritized; `@team-lead` agrees on scope
+
+### 2. Testability Adjustments — `@developer`
+- **Input:** coverage gap list
+- **Actions:** if code is not testable (tightly coupled, no DI, no interfaces) — make minimal structural changes to enable testing; do not change behavior; expose only what is needed for test injection
+- **Output:** updated code with improved testability on feature branch
+- **Done when:** `@qa` can write tests against the adjusted code without workarounds
+
+### 3. Automated Test Implementation — `@qa` + `@developer`
+- **Input:** gap list + testable code
+- **Actions:**
+  - unit tests: cover service logic with mocked repositories; cover repository logic with test DB or mocks
+  - integration tests: test API endpoints end-to-end with test client; verify DB state after mutations
+  - for each test: assert meaningful behavior, not implementation details; use clear `arrange / act / assert` structure
+  - `@developer` owns tests for complex internal logic; `@qa` owns scenario and contract tests
+- **Output:** new test files passing locally
+- **Done when:** all planned gaps covered; `make test` green
+
+### 4. Review of Scenarios & Assertions — `@team-lead`
+- **Input:** new test files
+- **Actions:** verify tests assert the right things (behavior, not internals); check that failure scenarios are realistically triggered; confirm test data setup is clean and isolated; flag brittle or non-deterministic tests
+- **Output:** review feedback (blocking: fix before merge / non-blocking: note for follow-up)
+- **Done when:** all blocking feedback resolved
+
+### 5. Stability Run & Reporting — `@qa`
+- **Input:** reviewed test suite
+- **Actions:** run full suite 3+ times in CI to confirm no flakiness; record final coverage metrics; produce `quality_report.md` with: coverage delta, scenario list, risk areas now covered, remaining known gaps
+- **Output:** `quality_report.md`; stable CI run evidence
+- **Done when:** zero flaky tests; coverage meets threshold; report complete
+
+## Exit
+Stable test suite + coverage threshold met + `@team-lead` approval = tests ready to merge.

package/areas/software/data-engineering/AGENTS.md

@@ -0,0 +1,59 @@
+# Data Engineering — guidance index
+
+## What this area covers
+
+Data pipeline engineering: dbt model development, data warehouse schema management, orchestration (Airflow / Prefect), data quality checks, lineage governance, SQL optimization, streaming patterns, and PII-safe data handling.
+
+## Guidance chain
+
+1. Project `.agent/` baseline (`AGENTS.md` + `.agent/*`)
+2. `software/general/rules/*` — always active
+3. `data-engineering/rules/*` — load all for this spec
+4. `data-engineering/skills/*/SKILL.md` — load only the skill matching the current task
+5. `data-engineering/workflows/*` — load the workflow matching the triggered command
+
+## Inherited from general
+
+- SDLC methodology and handoff contracts
+- Git / CI / lint and code style baselines
+
+## Data-engineering-specific constraints
+
+- PII data must never appear in development or test environments without explicit masking — no exceptions.
+- Schema changes follow the expand/contract pattern; no breaking changes to published marts without a migration plan.
+- Every pipeline has an idempotency guarantee: re-running produces the same result without duplication.
+- Data quality checks are part of the pipeline, not an afterthought — failing checks block downstream runs.
+
+## Spec map
+
+```text
+data-engineering/
+├── rules/
+│   ├── data-governance.md      ← data ownership, access tiers, retention policy
+│   ├── pii-handling.md         ← classification, masking, pseudonymization requirements
+│   ├── pipeline-integrity.md   ← idempotency, atomicity, failure recovery
+│   └── schema-management.md    ← expand/contract, versioning, backward compatibility
+├── skills/
+│   ├── data-modeling/SKILL.md        ← dimensional modeling, Kimball, Data Vault
+│   ├── dbt-patterns/SKILL.md         ← model structure, tests, macros, materializations
+│   ├── lineage-governance/SKILL.md   ← column-level lineage, OpenLineage, catalog integration
+│   ├── orchestration/SKILL.md        ← DAG design, SLA alerts, dependency management
+│   ├── quality-checks/SKILL.md       ← Great Expectations, dbt tests, anomaly detection
+│   ├── sql-optimization/SKILL.md     ← query plans, partitioning, clustering, cost
+│   └── streaming-patterns/SKILL.md   ← Kafka, Flink, exactly-once semantics, watermarks
+├── workflows/
+│   ├── new-model.md               ← /new-model
+│   ├── schema-migration.md        ← /schema-migration
+│   ├── backfill-data.md           ← /backfill-data
+│   ├── data-quality-incident.md   ← /data-quality-incident
+│   └── lineage-trace.md           ← /lineage-trace
+└── prompts/
+    └── *.md
+```
+
+## Discovery patterns
+
+- `rules/*.md`
+- `skills/*/SKILL.md`
+- `workflows/*.md`
+- `prompts/*.md`

package/areas/software/data-engineering/PROMPTS.md

@@ -0,0 +1,32 @@
+# PROMPTS: data-engineering
+
+Use these prompts with `AGENTS.md` from the same directory.
+
+## 1) Initialize agent behavior
+
+```text
+Read `data-engineering/AGENTS.md` and adopt its rules, skills loading strategy, and workflows as hard constraints.
+List the active rules and the selected workflow before implementation.
+```
+
+## 2) Implement a feature
+
+```text
+Using `data-engineering/AGENTS.md`, implement: <feature description>.
+Before coding: provide architecture notes, risk list, and test plan.
+After coding: run checks and report exact commands and results.
+```
+
+## 3) Incident / debug mode
+
+```text
+Using `data-engineering/AGENTS.md`, run incident triage for: <incident summary>.
+Return root cause hypotheses, validation steps, fix plan, and rollback plan.
+```
+
+## 4) Release readiness
+
+```text
+Using `data-engineering/AGENTS.md`, prepare release checklist for: <release scope>.
+Include quality gates, security gates, performance gates, and deployment validation.
+```

package/areas/software/data-engineering/prompts/backfill-data.md

@@ -0,0 +1,107 @@
+---
+workflow: backfill-data
+---
+
+# Prompt: `/backfill-data`
+
+Use when: reprocessing historical data after a pipeline fix, schema change, or new metric definition — safely and in batches.
+
+---
+
+## Example 1 — Pipeline fix backfill
+
+**EN:**
+```
+/backfill-data
+
+Reason: bug fix — revenue calculation excluded refunds for 47 days (2024-07-01 to 2024-08-16)
+Affected model: mart.orders_daily_summary (column: gross_revenue_usd)
+Fix deployed: 2024-08-17 (current data correct from this date)
+Backfill scope: 2024-07-01 → 2024-08-16 (47 days)
+Pipeline: Airflow DAG orders_daily_summary_dag
+Backfill strategy:
+  - Process in 7-day batches (avoid OOM on large joins)
+  - Batch order: oldest first (2024-07-01 → 2024-08-16)
+  - Run during off-peak hours (02:00–06:00 UTC)
+Downstream impact: BI dashboards consume this model — notify analytics team before start
+Validation: after backfill, compare gross_revenue_usd SUM for backfill period against Stripe dashboard (expected match within 0.1%)
+Idempotency: Airflow dag run with execution_date override; model uses INSERT OVERWRITE partition
+```
+
+**RU:**
+```
+/backfill-data
+
+Причина: исправление бага — расчёт revenue исключал возвраты в течение 47 дней (2024-07-01 по 2024-08-16)
+Затронутая модель: mart.orders_daily_summary (столбец: gross_revenue_usd)
+Исправление задеплоено: 2024-08-17 (текущие данные корректны с этой даты)
+Скоуп бэкфилла: 2024-07-01 → 2024-08-16 (47 дней)
+Pipeline: Airflow DAG orders_daily_summary_dag
+Стратегия бэкфилла:
+  - Обработка пакетами по 7 дней (избежать OOM на больших джойнах)
+  - Порядок пакетов: сначала старейшие (2024-07-01 → 2024-08-16)
+  - Запуск в нерабочие часы (02:00–06:00 UTC)
+Влияние на downstream: BI дашборды используют эту модель — уведомить analytics команду перед началом
+Валидация: после бэкфилла сравнить SUM gross_revenue_usd за период бэкфилла со Stripe dashboard (ожидаемое совпадение в пределах 0.1%)
+Идемпотентность: Airflow dag run с переопределением execution_date; модель использует INSERT OVERWRITE partition
+```
+
+---
+
+## Example 2 — New metric backfill
+
+**EN:**
+```
+/backfill-data
+
+Reason: new column added to mart.user_cohorts — ltv_90d (90-day lifetime value)
+Column exists in model since today, but historical rows have NULL
+Backfill scope: all users acquired before 2024-09-01 (need 90 days of order history to compute)
+Data available: stg_orders has full history back to 2022-01-01
+Strategy: single batch UPDATE using window function (manageable — 2M rows, < 5 min on ClickHouse)
+Downtime risk: UPDATE on columnar store — run during low-traffic window
+Validation: ltv_90d distribution should match manual Stripe cohort analysis (±5%)
+Rollback: snapshot table before UPDATE → mart.user_cohorts_backup_20240915
+```
+
+**RU:**
+```
+/backfill-data
+
+Причина: новый столбец добавлен в mart.user_cohorts — ltv_90d (lifetime value за 90 дней)
+Столбец существует в модели с сегодняшнего дня, но исторические строки имеют NULL
+Скоуп бэкфилла: все пользователи привлечённые до 2024-09-01 (нужно 90 дней истории заказов для расчёта)
+Доступные данные: stg_orders имеет полную историю начиная с 2022-01-01
+Стратегия: единовременный UPDATE с оконной функцией (управляемо — 2M строк, < 5 мин на ClickHouse)
+Риск простоя: UPDATE на колоночном хранилище — запускать в окно низкого трафика
+Валидация: распределение ltv_90d должно соответствовать ручному анализу когорт Stripe (±5%)
+Откат: снапшот таблицы до UPDATE → mart.user_cohorts_backup_20240915
+```
+
+---
+
+## Example 3 — Quick / Partition reprocess
+
+**EN:**
+```
+/backfill-data
+
+Reason: Kafka consumer lag caused 3 hours of missing events (2024-09-10 14:00–17:00 UTC)
+Events are available in DLQ — need to replay into raw.user_events
+Scope: single 3-hour partition (date=2024-09-10, hour IN (14,15,16))
+Method: replay from DLQ topic user_events_dlq → raw.user_events; downstream dbt models will auto-refresh
+Estimated volume: ~180 000 events (normal: 60k/hr)
+Validation: raw.user_events row count for affected hours matches DLQ message count
+```
+
+**RU:**
+```
+/backfill-data
+
+Причина: задержка Kafka consumer привела к 3 часам пропущенных событий (2024-09-10 14:00–17:00 UTC)
+События доступны в DLQ — нужно воспроизвести в raw.user_events
+Скоуп: одна 3-часовая партиция (date=2024-09-10, hour IN (14,15,16))
+Метод: воспроизведение из DLQ топика user_events_dlq → raw.user_events; downstream dbt модели обновятся автоматически
+Ожидаемый объём: ~180 000 событий (норма: 60k/ч)
+Валидация: количество строк raw.user_events для затронутых часов совпадает с количеством сообщений DLQ
+```

package/areas/software/data-engineering/prompts/data-quality-incident.md

@@ -0,0 +1,109 @@
+---
+workflow: data-quality-incident
+---
+
+# Prompt: `/data-quality-incident`
+
+Use when: a data quality issue is detected — wrong numbers in dashboards, failed dbt tests, or downstream consumer complaints — and needs systematic triage and remediation.
+
+---
+
+## Example 1 — Metric discrepancy in BI dashboard
+
+**EN:**
+```
+/data-quality-incident
+
+Incident: revenue metric in Looker dashboard shows $2.1M for August; finance team confirms actual = $2.4M (14% discrepancy)
+Detected: today (2024-09-02) by Finance during month-end close
+Impact: August MBR already sent with wrong numbers; investor deck in preparation
+Affected metric: gross_revenue_usd in mart.orders_daily_summary
+Last known correct: July revenue validated correctly
+Changes since July:
+  - currency normalisation refactored (PR #287, merged 2024-08-03)
+  - Stripe webhook consumer updated (PR #291, merged 2024-08-09)
+Immediate action: quarantine August data — add warning banner in Looker dashboard
+Investigation priority: compare mart revenue vs. Stripe dashboard daily for August; identify date of divergence
+Output: root cause identified, corrected August numbers, fix deployed, stakeholder communication
+```
+
+**RU:**
+```
+/data-quality-incident
+
+Инцидент: метрика revenue в Looker дашборде показывает $2.1M за август; финансовая команда подтверждает фактическое = $2.4M (расхождение 14%)
+Обнаружено: сегодня (2024-09-02) Финансами во время закрытия месяца
+Влияние: MBR за август уже отправлен с неверными цифрами; готовится презентация для инвесторов
+Затронутая метрика: gross_revenue_usd в mart.orders_daily_summary
+Последний известный корректный: revenue за июль валидирован корректно
+Изменения с июля:
+  - рефакторинг нормализации валюты (PR #287, слит 2024-08-03)
+  - обновлён Stripe webhook consumer (PR #291, слит 2024-08-09)
+Немедленное действие: карантин данных за август — добавить предупреждение в Looker дашборд
+Приоритет расследования: сравнить mart revenue vs. Stripe dashboard посуточно за август; определить дату расхождения
+Результат: корневая причина определена, скорректированные цифры за август, исправление задеплоено, коммуникация стейкхолдеров
+```
+
+---
+
+## Example 2 — dbt test failure in CI
+
+**EN:**
+```
+/data-quality-incident
+
+Incident: dbt CI run failed — 3 tests failing on morning run (2024-09-15 07:14 UTC)
+Failed tests:
+  - not_null — stg_orders.user_id: 847 NULL values (was 0 yesterday)
+  - unique — mart.orders_daily_summary.order_date+country: 12 duplicate rows
+  - accepted_values — stg_payments.status: unexpected value "pending_review" found
+Affected DAG: orders pipeline (blocked — downstream models not running)
+Data freshness: last successful run 2024-09-14 03:00 UTC
+Possible cause: Fivetran schema change — new NULL rule relaxed upstream; new payment status added by payment team
+Urgency: dashboards stale; finance report due at 12:00 UTC (4.5 hours)
+Immediate: unblock critical models (orders_daily_summary) while investigating nullable user_id
+```
+
+**RU:**
+```
+/data-quality-incident
+
+Инцидент: CI запуск dbt завершился с ошибкой — 3 упавших теста на утреннем запуске (2024-09-15 07:14 UTC)
+Упавшие тесты:
+  - not_null — stg_orders.user_id: 847 NULL значений (вчера было 0)
+  - unique — mart.orders_daily_summary.order_date+country: 12 дублирующихся строк
+  - accepted_values — stg_payments.status: найдено неожиданное значение "pending_review"
+Затронутый DAG: pipeline orders (заблокирован — downstream модели не запускаются)
+Свежесть данных: последний успешный запуск 2024-09-14 03:00 UTC
+Возможная причина: изменение схемы Fivetran — новое правило NULL ослаблено upstream; новый статус платежа добавлен payment командой
+Срочность: дашборды устаревшие; финансовый отчёт ожидается в 12:00 UTC (через 4.5 часа)
+Немедленно: разблокировать критические модели (orders_daily_summary) пока расследуем nullable user_id
+```
+
+---
+
+## Example 3 — Quick / Duplicate records detected
+
+**EN:**
+```
+/data-quality-incident
+
+Issue: mart.user_cohorts has duplicate user_id rows (unique test added today — was missing)
+Scope: 2 341 duplicate user_ids out of 840 000 total (0.28%)
+Root cause suspected: missing DISTINCT in stg_users CTE — users with multiple email verifications
+Impact: downstream: cohort analysis double-counts affected users; LTV metrics inflated by ~0.3%
+Fix: add DISTINCT on user_id to stg_users, re-run mart.user_cohorts
+Priority: medium (small %, dashboard numbers within acceptable tolerance)
+```
+
+**RU:**
+```
+/data-quality-incident
+
+Проблема: mart.user_cohorts содержит дублирующиеся строки user_id (unique тест добавлен сегодня — ранее отсутствовал)
+Скоуп: 2 341 дублирующихся user_id из 840 000 всего (0.28%)
+Предполагаемая причина: отсутствие DISTINCT в CTE stg_users — пользователи с несколькими подтверждениями email
+Влияние: downstream: анализ когорт двойной подсчёт затронутых пользователей; LTV метрики завышены на ~0.3%
+Исправление: добавить DISTINCT на user_id в stg_users, перезапустить mart.user_cohorts
+Приоритет: средний (маленький %, цифры дашборда в пределах допустимого отклонения)
+```

package/areas/software/data-engineering/prompts/lineage-trace.md

@@ -0,0 +1,121 @@
+---
+workflow: lineage-trace
+---
+
+# Prompt: `/lineage-trace`
+
+Use when: tracing the full upstream and downstream lineage of a dataset, column, or metric — to assess the blast radius of a change, investigate a data quality issue, or document data provenance.
+
+---
+
+## Example 1 — Blast radius analysis before a change
+
+**EN:**
+```
+/lineage-trace
+
+Direction: downstream (what will break if I change this?)
+Target: dbt model stg_orders (column: status)
+Proposed change: add new status value "partially_refunded" to accepted_values
+Trace depth: full — all downstream models, dashboards, and consumers
+Environment: dbt project (dbt Cloud), Looker BI, Kafka downstream consumers
+Expected graph:
+  stg_orders → int_order_aggregates → mart.orders_daily_summary → mart.user_cohorts
+                                     → mart.revenue_by_channel
+                                     → Looker Explore: "Orders"
+  stg_orders → Kafka topic: order_status_events → notification-service (consume)
+Identify: which models have accepted_values test on status (will fail if not updated);
+          which Looker dashboards filter on status values; which consumers handle status transitions
+Output: lineage-impact-report.md with change checklist per affected node
+```
+
+**RU:**
+```
+/lineage-trace
+
+Направление: downstream (что сломается если изменить это?)
+Цель: dbt модель stg_orders (столбец: status)
+Предлагаемое изменение: добавить новое значение статуса "partially_refunded" в accepted_values
+Глубина трассировки: полная — все downstream модели, дашборды и потребители
+Окружение: dbt проект (dbt Cloud), Looker BI, Kafka downstream потребители
+Ожидаемый граф:
+  stg_orders → int_order_aggregates → mart.orders_daily_summary → mart.user_cohorts
+                                     → mart.revenue_by_channel
+                                     → Looker Explore: "Orders"
+  stg_orders → Kafka топик: order_status_events → notification-service (потребление)
+Определить: какие модели имеют тест accepted_values на status (упадут если не обновить);
+            какие Looker дашборды фильтруют по значениям status; какие потребители обрабатывают переходы статусов
+Результат: lineage-impact-report.md с чеклистом изменений для каждого затронутого узла
+```
+
+---
+
+## Example 2 — Root cause trace for a data quality issue
+
+**EN:**
+```
+/lineage-trace
+
+Direction: upstream (where does this bad data come from?)
+Target: mart.orders_daily_summary — column gross_revenue_usd shows 14% lower than expected for August
+Trace upstream from: mart.orders_daily_summary
+Intermediate models: int_order_financials → stg_orders, stg_payments, stg_exchange_rates
+Source tables: raw.stripe_events (Fivetran), raw.orders (app DB replica)
+Investigation steps:
+  1. Check gross_revenue_usd at each layer: raw → staging → intermediate → mart
+  2. Find the layer where discrepancy first appears
+  3. Check if stg_exchange_rates has correct rates for August (EUR→USD rate changed significantly in August)
+  4. Check stg_payments filter — are refunds being excluded or double-counted?
+Output: layer-by-layer discrepancy table; identified transformation step where values diverge
+```
+
+**RU:**
+```
+/lineage-trace
+
+Направление: upstream (откуда берутся эти плохие данные?)
+Цель: mart.orders_daily_summary — столбец gross_revenue_usd показывает на 14% меньше ожидаемого за август
+Трассировка upstream от: mart.orders_daily_summary
+Промежуточные модели: int_order_financials → stg_orders, stg_payments, stg_exchange_rates
+Исходные таблицы: raw.stripe_events (Fivetran), raw.orders (реплика app DB)
+Шаги расследования:
+  1. Проверить gross_revenue_usd на каждом слое: raw → staging → intermediate → mart
+  2. Найти слой где впервые появляется расхождение
+  3. Проверить есть ли в stg_exchange_rates корректные курсы за август (курс EUR→USD существенно изменился в августе)
+  4. Проверить фильтр stg_payments — возвраты исключаются или учитываются дважды?
+Результат: таблица расхождений по слоям; определённый шаг трансформации где значения расходятся
+```
+
+---
+
+## Example 3 — Compliance / data provenance audit
+
+**EN:**
+```
+/lineage-trace
+
+Purpose: GDPR Article 30 audit — document where user PII flows in our data platform
+Starting point: raw.users (source of truth for PII: email, name, phone)
+Trace: all models and tables that contain or derive from PII fields (email, user_id, name, phone)
+Include: dbt models, BI exports, data shares, ML feature store
+Flag: any PII that reaches:
+  - External BI tools (Looker, Metabase) — must confirm row-level security in place
+  - ML training datasets — must confirm pseudonymisation or removal
+  - Cold storage / archives — must confirm retention policy enforced
+Output: PII lineage map (mermaid diagram) + compliance checklist per destination
+```
+
+**RU:**
+```
+/lineage-trace
+
+Назначение: аудит GDPR Статья 30 — задокументировать куда PII пользователей попадает в нашей data платформе
+Начальная точка: raw.users (источник истины для PII: email, имя, телефон)
+Трассировать: все модели и таблицы которые содержат или являются производными от PII полей (email, user_id, имя, телефон)
+Включить: dbt модели, BI экспорты, data shares, ML feature store
+Отметить: любой PII который достигает:
+  - Внешние BI инструменты (Looker, Metabase) — подтвердить наличие row-level security
+  - ML обучающие датасеты — подтвердить псевдоанонимизацию или удаление
+  - Холодное хранилище / архивы — подтвердить соблюдение политики хранения
+Результат: карта PII lineage (mermaid диаграмма) + чеклист соответствия для каждого назначения
+```

package/areas/software/data-engineering/prompts/new-model.md

@@ -0,0 +1,117 @@
+---
+workflow: new-model
+---
+
+# Prompt: `/new-model`
+
+Use when: scaffolding a new dbt model with sources, staging, mart layers, YAML documentation, and data quality tests.
+
+---
+
+## Example 1 — Domain mart model
+
+**EN:**
+```
+/new-model "orders_daily_summary"
+
+Layer: mart (business-facing, consumed by BI dashboards)
+Source data:
+  - stg_orders: order_id, user_id, status, created_at, total_amount, currency
+  - stg_order_items: order_id, product_id, quantity, unit_price
+  - stg_users: user_id, country, acquisition_channel
+Grain: one row per (date, country, acquisition_channel)
+Metrics to compute:
+  - order_count, gross_revenue_usd, avg_order_value_usd
+  - new_users_who_ordered (first order in period)
+  - refund_count, refund_amount_usd
+Currency: normalise all amounts to USD (use exchange_rates seed table)
+Materialisation: table (refreshed daily via Airflow DAG at 03:00 UTC)
+Tests required: not_null on date + country, accepted_values for status, referential integrity order_id
+Output: models/mart/orders_daily_summary.sql + schema.yml with column descriptions
+```
+
+**RU:**
+```
+/new-model "orders_daily_summary"
+
+Слой: mart (для бизнеса, используется BI дашбордами)
+Исходные данные:
+  - stg_orders: order_id, user_id, status, created_at, total_amount, currency
+  - stg_order_items: order_id, product_id, quantity, unit_price
+  - stg_users: user_id, country, acquisition_channel
+Гранулярность: одна строка на (дата, страна, канал привлечения)
+Вычисляемые метрики:
+  - order_count, gross_revenue_usd, avg_order_value_usd
+  - new_users_who_ordered (первый заказ за период)
+  - refund_count, refund_amount_usd
+Валюта: нормализовать все суммы в USD (использовать seed таблицу exchange_rates)
+Материализация: table (обновляется ежедневно через Airflow DAG в 03:00 UTC)
+Обязательные тесты: not_null на date + country, accepted_values для status, referential integrity order_id
+Результат: models/mart/orders_daily_summary.sql + schema.yml с описаниями столбцов
+```
+
+---
+
+## Example 2 — Staging model from raw source
+
+**EN:**
+```
+/new-model "stg_stripe_payments"
+
+Layer: staging (clean and rename raw Stripe webhook events)
+Source: raw.stripe_events table (loaded by Fivetran)
+Raw schema: id, type, data (JSON), created (Unix timestamp), livemode
+Filter: type IN ('payment_intent.succeeded', 'payment_intent.payment_failed', 'charge.refunded')
+Transformations:
+  - Parse data JSON: extract payment_intent_id, amount, currency, customer_id, metadata.order_id
+  - Convert created (Unix) to timestamp_tz
+  - Rename: id → stripe_event_id, amount → amount_cents (keep raw cents)
+  - Add derived: amount_usd = amount_cents / 100.0
+Materialisation: view (no storage cost; always fresh)
+Tests: unique(stripe_event_id), not_null(stripe_event_id, payment_intent_id, created_at)
+```
+
+**RU:**
+```
+/new-model "stg_stripe_payments"
+
+Слой: staging (очистка и переименование сырых Stripe webhook событий)
+Источник: таблица raw.stripe_events (загружается Fivetran)
+Сырая схема: id, type, data (JSON), created (Unix timestamp), livemode
+Фильтр: type IN ('payment_intent.succeeded', 'payment_intent.payment_failed', 'charge.refunded')
+Трансформации:
+  - Парсинг JSON поля data: извлечь payment_intent_id, amount, currency, customer_id, metadata.order_id
+  - Конвертировать created (Unix) в timestamp_tz
+  - Переименовать: id → stripe_event_id, amount → amount_cents (оставить сырые центы)
+  - Добавить производный: amount_usd = amount_cents / 100.0
+Материализация: view (без затрат на хранение; всегда актуально)
+Тесты: unique(stripe_event_id), not_null(stripe_event_id, payment_intent_id, created_at)
+```
+
+---
+
+## Example 3 — Quick / Intermediate model
+
+**EN:**
+```
+/new-model "int_user_order_stats"
+
+Layer: intermediate (joins for downstream mart reuse)
+Logic: for each user — total_orders, total_spent_usd, first_order_date, last_order_date, days_since_last_order
+Sources: stg_orders (already exists), stg_payments (already exists)
+Include only: completed orders (status = 'paid')
+Materialisation: ephemeral (no table — inlined into mart queries)
+No additional tests needed — covered by upstream staging tests
+```
+
+**RU:**
+```
+/new-model "int_user_order_stats"
+
+Слой: intermediate (джойны для переиспользования в mart)
+Логика: для каждого пользователя — total_orders, total_spent_usd, first_order_date, last_order_date, days_since_last_order
+Источники: stg_orders (уже существует), stg_payments (уже существует)
+Включать только: завершённые заказы (status = 'paid')
+Материализация: ephemeral (без таблицы — встраивается в mart запросы)
+Дополнительные тесты не нужны — покрыты тестами вышестоящего staging слоя
+```