ai-developer-skill-os 9.1.2 → 9.3.0

package/.agents/skills/qk-data-engineer/SKILL.md

@@ -1,9 +1,9 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-data-engineer
-version: 9.1.0
+version: 9.2.0
 status: stable
-description: "Universal Data Engineering Skill — Tự động thích nghi với project context, áp dụng các best practices (Idempotency, Data Quality, Lineage, Security) không giới hạn tech stack."
+description: "Thiết kế và implement data pipeline với best practices: idempotency, data quality gate, lineage, incremental processing. Dùng skill này khi user nhắc đến: data pipeline, etl, elt, dbt, dbt model, airflow dag, spark job, medallion architecture, data quality, incremental load, schema evolution, backfill, data warehouse — kể cả khi chỉ nói \"load data từ X sang Y\"."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 # ── V9: Classification ─────────────────────────────────────
@@ -24,16 +24,19 @@ complexity:
     has_breaking_change: false
 
 triggers:
-  - "data engineer"
+  - "data pipeline"
   - "etl"
   - "elt"
-  - "data pipeline"
+  - "dbt"
   - "dbt model"
-  - "spark job"
   - "airflow dag"
-  - "data quality gate"
-  - "medallion"
-  - "iceberg"
+  - "spark job"
+  - "medallion architecture"
+  - "data quality"
+  - "incremental load"
+  - "schema evolution"
+  - "backfill"
+  - "data warehouse"
 
 selection:
   priority: high
@@ -54,7 +57,6 @@ tools:
 related_skills:
   - qk-data-lifecycle
   - qk-db-optimizer
-  - qk-validation-gate
 
 knowledge_scope:
   owns:
@@ -103,372 +105,149 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
----
-
-## Memory Workflow (Universal Project Knowledge V1 Protocol)
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture (vd: Lakehouse layout, Medallion structure, storage prefixes)
-  - Hard Bug (vd: API pagination loss, composite keys mismatch, partition pruning bug)
-  - Convention (vd: naming snake_case, schema compatibility rules)
-  - Pattern (vd: Ingestion template, Quality Gate assertions)
-  - Tech Debt Pattern
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**. Không được xem Memory là Source of Truth. Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn (vd: lỗi sort watermark khi nạp gia tăng).
-  - Pattern làm việc lặp lại trong dự án (vd: template contract JSON, schema DDL, DAG wrapper).
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức, lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua `/learn` hoặc `qk-project-memory`.
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data / raw sample payloads.
-- Output của một lần chạy test/scan/quality gate tạm thời.
-- Lỗi nhỏ cú pháp SQL/Python chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-## Source-of-Truth Hierarchy
-
-Khi có sự mâu thuẫn thông tin giữa các nguồn, AI **BẮT BUỘC** giải quyết theo thứ tự ưu tiên giảm dần:
-
-1. **Explicit user instruction** (Chỉ thị trực tiếp từ người dùng trong phiên làm việc)
-2. **Current production / project configuration** (Cấu hình thực tế đang chạy: YAML, JSON, env)
-3. **Current source code + tests** (Mã nguồn và bài kiểm thử đang có trong repository)
-4. **Current project documentation** (Tài liệu đặc tả, bàn giao kỹ thuật cập nhật của dự án)
-5. **Approved project knowledge / memory** (`.ai-local/knowledge/index.yaml`)
-6. **Generic engineering best practices** (Tiêu chuẩn kỹ thuật chung của ngành)
-7. **Model inference** (Suy luận ngầm định của mô hình AI)
-
-> ⚠️ *Never let a lower-priority source override a higher-priority source.*
+Chịu trách nhiệm thiết kế và hiện thực hóa các đường ống dữ liệu (Data Pipelines: ETL/ELT) tuân thủ nghiêm ngặt 4 trụ cột kỹ thuật dữ liệu: **Idempotency (Tính lũy thừa) → Data Quality Gate (Cổng kiểm tra chất lượng) → Lineage (Nguồn gốc luồng dữ liệu) → Incremental Processing (Xử lý gia tăng)**.
 
 ---
 
 ## Preconditions
 
-### Required for Implementation
-- [ ] Xác định được mục tiêu hoặc phạm vi task (New pipeline, debug, modify, optimize, v.v.).
-- [ ] Đã thực hiện Pre-flight Inspection phát hiện Tech Stack, Architecture và Conventions của dự án.
+Trước khi xây dựng hoặc cập nhật pipeline dữ liệu, AI BẮT BUỘC kiểm tra:
 
-### Required When Applicable
-- [ ] Data Contract / Schema DDL (Bắt buộc khi implement/modify pipeline; Không bắt buộc nếu task là discovery/tạo contract mới).
-- [ ] Business Grain & Primary Key (Khi thiết kế Data Model hoặc Incremental pipeline).
-- [ ] Incremental Cursor / Watermark strategy (Khi xây dựng luồng nạp gia tăng).
+- [ ] Xác định Data stack từ `.agents/DEV_PROFILE.md` (Orchestrator: Airflow/Prefect, Warehouse: BigQuery/Snowflake/Postgres, Transformation: dbt/Spark/Pandas).
+- [ ] Xác định chiến lược Idempotency (Upsert, Merge, Partition overwrite, Watermarking).
+- [ ] Xác định ngưỡng Data Quality Gates (Null check, Uniqueness, Volume anomaly, Freshness).
+- [ ] Nếu pipeline không có cơ chế Idempotent (chạy lại gây duplicate dữ liệu) hoặc thiếu validation:
+  → **EXIT: BLOCKED**
+  → Báo cáo user yêu cầu xác định deduplication key / partition strategy trước khi code.
 
 ---
 
-## Scope & Core Principles
-
-### Core Principles (Thứ tự ưu tiên cốt lõi)
-1. **Correctness & Data Integrity**: Dữ liệu phải phản ánh chính xác nghiệp vụ. Không đánh đổi tính đúng đắn để lấy tốc độ.
-2. **Idempotency & Fault Tolerance**: Mọi pipeline phải an toàn khi chạy lại nhiều lần (re-run không nhân bản dữ liệu, không sinh rác).
-3. **Data Quality**: Luôn có chốt chặn kiểm tra tự động trước khi publish dữ liệu.
-4. **Schema & Contract Discipline**: Schema and Data Contract are explicit compatibility boundaries and must be versioned when changed.
-5. **Observability & Lineage**: Mọi bản ghi phải truy vết được nguồn gốc theo cơ chế lineage của dự án.
-6. **Security & Privacy**: Apply the project's approved privacy/protection mechanism (masking, tokenization, encryption); never expose sensitive data or credentials.
-7. **Performance & Cost**: Tối ưu partitioning, clustering, query plan nhưng không phá vỡ tính đúng đắn.
-8. **Maintainability & Simplicity**: Code tường minh, dễ đọc và dễ bàn giao.
-
-### This skill does:
-- ✅ Tự động thích nghi với hệ sinh thái dữ liệu của dự án (Spark, dbt, Airflow, Dagster, Snowflake, Iceberg, BigQuery...).
-- ✅ Thiết kế và xây dựng Data Pipelines (ETL/ELT) an toàn, idempotent.
-- ✅ Thiết kế Data Modeling (Medallion, Star Schema, OBT) phù hợp workload.
-- ✅ Quản lý Data Contracts, Schema Evolution và phát hiện Breaking Changes.
-- ✅ Cài đặt Data Quality Gates với Severity Matrix (CRITICAL, ERROR, WARNING, INFO).
-- ✅ Tối ưu hiệu năng truy vấn, compaction, layout và tài nguyên compute.
-- ✅ Debugging và điều tra sự cố dữ liệu (Lineage, Snapshot, PIR).
-
-### This skill does NOT:
-- ❌ Tự ý chọn tech stack mới nếu dự án chưa dùng hoặc chưa có yêu cầu.
-- ❌ Sửa ngầm logic tính toán hoặc schema production mà không có Impact Analysis.
-- ❌ Bỏ qua Data Quality Gate chỉ để pipeline "chạy xanh".
-- ❌ Tuyên bố "Production-Ready" khi chỉ mới vượt qua unit test ở môi trường local.
+## Scope
 
----
-
-## Rules & Decision Rules
+✅ Skill này làm:
+- Thiết kế và cài đặt dbt models (Staging → Intermediate → Marts), Spark jobs, Airflow DAGs.
+- Cấu hình chiến lược Incremental load (Timestamp watermarking, CDC, Partition replacement).
+- Thiết lập Data Quality Assertions (dbt tests, Great Expectations, Soda checks).
+- Quản lý Schema Evolution (thay đổi cột an toàn, chống silent failure / schema drift).
+- Viết tài liệu Lineage và từ điển dữ liệu (Data Dictionary).
 
-### Rules Bắt Buộc
-- ❌ **No Stack Hallucination**: Không tự chọn dbt/Spark/Airflow nếu project chưa sử dụng.
-- ❌ **No Schema Guessing**: Schema từ Data Contract/DDL là Source of Truth, không đoán mò từ sample JSON.
-- ❌ **Authoritative Path & Location Builder**: Ưu tiên sử dụng cơ chế sinh đường dẫn/vị trí lưu trữ chính thức của dự án. Tuyệt đối không tự bịa hoặc nối chuỗi path thủ công khi dự án đã cung cấp module chuẩn.
-- ❌ **Preserve Authoritative Lineage**: Tuân thủ hoặc triển khai cơ chế lineage chuẩn của dự án (OpenLineage, metadata columns, audit tables). Nếu dự án chưa có, đề xuất chiến lược lineage tối thiểu phù hợp với nền tảng.
-- ❌ **No Silent Behavior Mutation**: Thay đổi nghiệp vụ phải kèm migration strategy và impact analysis.
-
-### Decision Rules
-- **IF** project has existing orchestration framework **→ USE IT**.
-- **IF** project has existing Data Contracts **→ CONTRACT IS SOURCE OF TRUTH**.
-- **IF** task requires incremental processing **→** Xác định Watermark & Dedup; **KHÔNG** sort theo watermark khi phân trang API.
-- **IF** transformation has both Deduplication & PII Masking **→** Áp dụng các phép biến đổi theo yêu cầu hợp đồng và quy tắc bảo mật; khi cần cả hai, **BẮT BUỘC** duy trì thứ tự phụ thuộc (khử trùng lặp trước khi che thông tin để không làm mất khóa định danh).
-- **IF** architecture choice materially affects data correctness, security, cost, downstream compatibility, or production architecture **→ BLOCKED / request decision**.
-- **ELSE** (Quyết định kiến trúc nhỏ/không gây rủi ro phá vỡ) **→** Chọn phương án ít gây bất ngờ nhất, đồng bộ với convention dự án và ghi rõ lý do (rationale).
-- **IF** requested change can break downstream consumers **→** Thực hiện Impact Analysis trước khi thay đổi.
+❌ Skill này KHÔNG làm:
+- Thiết kế UI Dashboard hay biểu đồ trên web app (→ `qk-ui-builder`).
+- Viết CRUD REST API cho web backend thông thường (→ `qk-api-lifecycle`).
+- Quản lý hạ tầng cụm máy chủ vật lý / Kafka cluster (→ `qk-devops-platform`).
 
 ---
 
-## Priority Order
-
-| Priority | Task | Skip Threshold |
-|----------|------|----------------|
-| P1 | Pre-flight Stack, Convention & Contract Discovery | Never |
-| P2 | Schema Validation & Breaking Change Check | Never |
-| P3 | Idempotency & Re-run Safety Design | Never |
-| P4 | Data Quality Assertions (Row integrity, required fields, key uniqueness) | Never |
-| P5 | Security & Privacy Protections Applied | Never |
-| P6 | Layout Tuning (Partitioning/Clustering/Compaction) | When applicable |
+## Execution Steps
 
----
-
-## Execution Backbone & Workflow Router
-
-### Execution Backbone
-Mọi yêu cầu Data Engineering đều được thực thi theo chuỗi xử lý bất biến sau:
-
-```text
-USER REQUEST
-    ↓
-TASK CLASSIFICATION
-    ↓
-PROJECT CONTEXT (Pre-flight Inspection)
-    ↓
-SOURCE-OF-TRUTH RESOLUTION
-    ↓
-RULE RESOLUTION
-    ↓
-WORKFLOW ROUTER
-    ↓
-COMMON GATES (Discover ➔ Design ➔ Impact Analysis ➔ Implement ➔ Test ➔ QA ➔ Verify ➔ Report)
+### Step 1 — Source Analysis & Data Contract
 ```
-
----
-
-### Workflow Router
-
-Khi phân loại xong task, AI điều hướng vào workflow chuyên biệt:
-
-#### 1. `NEW_PIPELINE` / `etl`
-1. **Discover**: Đọc source schema, stack, existing storage conventions.
-2. **Design**: Xác định source, target, partitioning, load strategy (overwrite_partition, upsert, append).
-3. **Contract**: Tạo hoặc cập nhật Data Contract (fields, types, nullability, PII).
-4. **Implement**: Viết transformation (bảo toàn thứ tự dedup/masking) và bảo đảm Idempotency.
-5. **Quality & Test**: Khai báo assertions và viết unit tests.
-6. **Verify**: Chạy tests, đánh giá trạng thái xác minh.
-
-#### 2. `MODIFY_PIPELINE`
-1. **Inspect**: Đọc code hiện tại, DAG dependencies, configs và tests liên quan.
-2. **Impact Analysis**: Xác định downstream tables, views, dashboards bị ảnh hưởng.
-3. **Compatibility**: Kiểm tra breaking changes đối với schema hiện hữu.
-4. **Implement**: Áp dụng thay đổi tối thiểu, cập nhật contracts & unit tests.
-5. **Quality Gate**: Chạy lại toàn bộ test suite để chống regression.
-
-#### 3. `DEBUG` / `INCIDENT`
-1. **Reproduce**: Tái hiện lỗi với payload hoặc điều kiện lỗi.
-2. **Isolate**: Xác định tầng lỗi (Ingest, Staging, Transform, Quality Gate).
-3. **Inspect**: Tra cứu logs, lineage, snapshot metadata, raw landing payload.
-4. **Root Cause**: Phân tích nguyên nhân gốc rễ (pagination drift, timezone, null pointer).
-5. **Fix & Regression Test**: Sửa lỗi phạm vi tối thiểu, bổ sung regression test và báo cáo PIR.
-
-#### 4. `DATA_MODELING`
-1. **Query Patterns**: Phân tích nhu cầu đọc và SLA của consumer/dashboard.
-2. **Paradigm**: Chọn mô hình phù hợp (Medallion, Star Schema, OBT, Data Vault).
-3. **Grain & Keys**: Định nghĩa Primary Key, Business Key, Foreign Keys và Partitioning key.
-4. **Contract & DDL**: Sinh contract và DDL tường minh.
-
-#### 5. `DATA_QUALITY`
-1. **Asset Profiling**: Liệt kê các bảng và trường cần giám sát.
-2. **Severity Matrix**: CRITICAL (dừng pipeline), ERROR (chặn publish), WARNING (alert), INFO (log metric).
-3. **Assertions**: Cài đặt kiểm tra toàn vẹn dòng (row integrity), trường bắt buộc (not_null), khóa duy nhất (unique), và mở rộng freshness/referential/consistency.
-
-#### 6. `SCHEMA_EVOLUTION`
-1. **Version Diff**: So sánh Schema V_Old vs V_New.
-2. **Classify**: Phân loại Backward Compatible vs Breaking Change.
-3. **Migration Plan**: Viết migration script, xử lý default values và nâng `contract_version`.
-4. **Downstream Validation**: Kiểm tra tính tương thích của views/queries.
-
-#### 7. `BACKFILL` / `REPLAY`
-1. **Scope & Window**: Xác định time window (from_date ➔ to_date) và partitions mục tiêu.
-2. **Isolation**: Dùng partition replacement hoặc atomic merge để không ảnh hưởng dữ liệu đang vận hành.
-3. **Reconcile**: Đối chiếu tổng số dòng và giá trị metric trước/sau backfill.
-
-#### 8. `OPTIMIZE`
-1. **Profile**: Đo thời gian chạy, bytes scanned, memory skew, partition layout.
-2. **Bottlenecks**: Tìm full-table scans, shuffle spills, small files problem.
-3. **Tune**: Rewrite queries (pushdown filters), optimize layout (compaction, Z-Order), tune executor configs.
-4. **Verify Correctness**: Đảm bảo kết quả dữ liệu TRƯỚC và SAU tối ưu hoàn toàn trùng khớp.
-
----
-
-## Output Format
-
-```markdown
-🔧 Data Engineer Task Summary
-─────────────────────────────────────────────────
-Scope:          [Mô tả ngắn gọn phạm vi: ETL / Debug / Quality Gate / Modeling / Optimize]
-Tech Stack:     [Ecosystem & công cụ đã detect/sử dụng]
-Target Tables:  [Danh sách bảng/datasets liên quan]
-
-📋 Architecture & Assumptions:
-  - Architecture:  [Medallion / Star Schema / OBT / Staging-Mart]
-  - Load Strategy: [Overwrite Partition / Upsert / Append]
-  - Assumptions:   [Các giả định kỹ thuật & nghiệp vụ đã áp dụng]
-
-Changes Applied:
-  ✅ [Action 1]: [Chi tiết những gì đã làm, file đã sửa/tạo]
-  ✅ [Action 2]: [Chi tiết về xử lý logic / contract / transform]
-
-📊 Data Integrity & Quality:
-  - Idempotency:   [Cơ chế đảm bảo chạy lại an toàn]
-  - Quality Gate:  [Các assertions đã khai: row integrity, required fields, unique, freshness, referential]
-  - Lineage:       [Cơ chế lineage áp dụng: OpenLineage / audit columns / metadata]
-
-✅ Verification Status:
-  - Unit Tests:    [Pass / N/A / X tests run]
-  - Quality Gate:  [Passed / Configured]
-  - Environment:   [Local Unit Verified / Real Infra Pending]
-
-⚠️ Risks, Trade-offs & Next Steps:
-  - [Các lưu ý về performance, schema compatibility hoặc việc cần test trên cụm thật]
+Inputs:  Yêu cầu pipeline từ user, Source schema, Volume ước tính
+Actions:
+  - Phân tích cấu trúc nguồn dữ liệu (Source freshness, Primary keys, Update timestamps).
+  - Thỏa thuận Data Contract giữa nhà cung cấp dữ liệu và Data Warehouse.
+  - Xác định partition strategy (theo date/hour) và clustering keys.
+Output: Pipeline Architectural Plan & Contract
 ```
 
----
-
-## Exit Codes
-
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | Pipeline/Model/Fix implemented, verified, QA passed | All checks passed |
-| PARTIAL | Code done but verification on real infra is pending | Needs live cluster run |
-| BLOCKED | Required information remains unavailable after reasonable project inspection | Missing critical specifications |
-| FAILED | Quality gate failed, breaking change without migration | Security/Integrity violation |
-
----
-
-## Confidence Model
-
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | Stack detected, contract exists, clear source-target mapping | Implement end-to-end |
-| MEDIUM | Stack clear but contract or grain partially undefined | State assumptions, proceed with least-surprising option |
-| LOW / UNKNOWN | Source API/schema completely unknown | Discovery first ➔ Inspect repo/sources before blocking |
-
----
-
-## Severity
-
-| Level | Definition | Action |
-|-------|-----------|--------|
-| CRITICAL | Pipeline failure, data loss, duplicate primary keys | Dừng pipeline ngay lập tức |
-| ERROR | Schema mismatch, null in required column | Chặn publish sang tầng tiếp theo |
-| WARNING | Freshness SLA breach, statistical value drift | Bắn alert nhưng cho phép publish |
-| INFO | Metadata metric logging, row count audit | Ghi log theo dõi |
-
----
-
-## Evidence Format
-
+### Step 2 — Transformation & Idempotent Logic
 ```
-[SEVERITY] path/to/pipeline_or_query.py:LINE
-Issue:      [specific data issue or failure mode]
-Confidence: HIGH
-Fix:        [specific change / assertion]
+Inputs:  Contract, Tech stack
+Actions:
+  - Viết code transformation (SQL/Python/PySpark) chia theo các tầng Medallion (Bronze/Silver/Gold).
+  - Đảm bảo logic tính toán có tính lũy thừa (Idempotent): rerun nhiều lần không thay đổi kết quả.
+  - Tối ưu hóa câu query xử lý dữ liệu lớn (Pruning partitions, tránh full table scan).
+Output: Transformation scripts & Models
 ```
 
-**Example:**
+### Step 3 — Quality Gates & Anomaly Checks
 ```
-[CRITICAL] src/jobs/transform_silver.py:45
-Issue:      Deduplication performed AFTER PII masking, losing original identity key
-Confidence: HIGH
-Fix:        Reorder steps: Cast -> Deduplicate -> PII Masking -> Lineage
+Inputs:  Transformation scripts
+Actions:
+  - Thêm tests bắt buộc: Not null, Unique, Referential integrity (Foreign keys).
+  - Thêm row count checks và freshness sensors để phát hiện dữ liệu rỗng bất thường.
+  - Cấu hình cơ chế cảnh báo (Alert) khi chất lượng dữ liệu không đạt chuẩn.
+Output: Test suite & Monitoring rules
 ```
 
----
-
-## Retry Policy
+### Step 4 — Verification & Dry Run
 ```
-Quality Gate or Pipeline execution fails
-  └─ Inspect failure layer & error logs
-       ├─ Data schema mismatch → Update contract or fix mapping → Retry 1 time
-       └─ Data corruption in source → EXIT: FAILED → Alert human engineer
+Inputs:  Pipeline code & Quality tests
+Actions:
+  - Kiểm tra cú pháp, compile SQL/dbt models.
+  - Xác nhận kế hoạch backfill dữ liệu lịch sử an toàn.
+Exit: SUCCESS nếu pipeline bảo đảm tính idempotent và pass mọi quality gates.
 ```
 
 ---
 
-## Escalation Rules
+## Prompt Template
+
+AI đọc `DEV_PROFILE.md` để biết data stack (pipeline/warehouse/format/broker).
+Mô tả pipeline cần làm — AI sẽ thiết kế theo đúng tool đang dùng.
+
 ```
-BLOCKED: Critical architectural decision needed or breaking schema detected
-Missing:
-  - Source-to-target field mapping
-  - Migration plan for breaking schema change
-Questions:
-  1. Trường mới/đổi kiểu có migration plan chưa?
-  2. Quyết định kiến trúc này có ảnh hưởng tới hạ tầng production không?
-Recommended Assumptions (if proceeding with minor choice):
-  - Choose least-surprising project-consistent option
-  - Document rationale in summary report
+Pipeline:    [Tên pipeline / DAG / job]
+Source:      [Nguồn dữ liệu: DB / API / file / stream / ...]
+Destination: [Đích: warehouse / data lake / another DB / ...]
+Frequency:   [Batch daily / hourly / streaming / event-driven]
+Volume:      [Số rows / GB ước tính mỗi lần chạy]
+SLA:         [Data phải có mặt lúc mấy giờ? Latency tối đa?]
+Rules:       [Idempotency, dedup, schema evolution, data quality gate]
 ```
 
 ---
 
-## Handoff Contract
+### Ví dụ theo tech stack:
 
-### Consumes
-```json
-{
-  "from": "user or qk-orchestrator",
-  "required_fields": ["task"],
-  "optional_fields": ["source", "target", "contract_path", "load_strategy", "profile"]
-}
+**dbt + BigQuery + Airflow**
+```
+Pipeline:    daily_order_metrics
+Source:      PostgreSQL (production DB) — bảng orders, order_items, products
+Destination: BigQuery dataset: mart — table: fct_order_metrics
+Frequency:   Daily batch lúc 3AM UTC
+Volume:      ~50k rows/ngày, tăng trưởng 10%/tháng
+SLA:         Data sẵn sàng trước 6AM UTC cho dashboard
+Rules:       - Idempotent: re-run ngày bất kỳ cho kết quả giống nhau
+             - Không load ngày hiện tại (incomplete data)
+             - Alert nếu row count giảm > 20% so với 7 ngày trước
+             - Schema thay đổi ở source → fail loud, không silent corrupt
 ```
+→ AI thiết kế: dbt model layers (staging → intermediate → mart),
+  Airflow DAG với sensor check source freshness, incremental model strategy
+  (merge key = order_id + date), dbt test (not_null, unique, accepted_values),
+  partition by date trên BQ để tránh full scan, audit log table.
 
-### Produces
-```json
-{
-  "to": "user or qk-validation-gate",
-  "output_fields": ["pipeline_code", "contract_spec", "quality_gate_config", "exit_code"]
-}
+**Spark + Delta Lake + Databricks**
+```
+Pipeline:    clickstream_sessionization
+Source:      Kafka topic: user.clicks — ~5M events/ngày
+Destination: Delta Lake: /data/gold/user_sessions
+Frequency:   Micro-batch mỗi 5 phút (Structured Streaming)
+Volume:      ~3.5GB/ngày raw
+SLA:         Session data available trong vòng 10 phút kể từ event
+Rules:       - Session timeout: 30 phút không activity
+             - Exactly-once processing
+             - Backfill safe (có thể re-process từ Kafka offset)
+```
+→ AI thiết kế: Spark Structured Streaming với watermark cho late data,
+  session window aggregation, Delta Lake MERGE cho upsert sessions,
+  checkpoint location strategy, schema enforcement + evolution,
+  Z-ORDER optimization cho query patterns, monitoring (lag metrics).
+
+**Airbyte + dbt + Snowflake**
+```
+Pipeline:    crm_sync — Salesforce → Snowflake → mart
+Source:      Salesforce (Airbyte connector) — objects: Account, Opportunity, Contact
+Destination: Snowflake RAW → STAGING → MART
+Frequency:   Airbyte sync mỗi 1 giờ, dbt transform mỗi 2 giờ
+Volume:      ~500k records total, delta ~2k/ngày
+SLA:         CRM data lag tối đa 3 giờ so với Salesforce
+Rules:       - Không xóa hard delete từ source (soft delete pattern)
+             - PII fields (email, phone) phải masked trong MART layer
+             - Lineage từ Salesforce ID phải traceable đến mart row
 ```
+→ AI thiết kế: Airbyte connection config + normalization settings,
+  dbt source freshness test, PII masking macro, soft-delete handling
+  (dbt snapshot vs custom), column-level lineage documentation,
+  Snowflake role-based access cho MART vs RAW.