---
paths:
  - "**/*"
domain: "common"
---

# AutoPOE2 - Common Development Workflow & Invariants

> **Tài liệu quy chuẩn phát triển chung áp dụng cho mọi tác tử và kỹ sư trong workspace AutoPOE2.**  
> Mở rộng từ Hiến pháp SSoT tại [`AGENTS.md`](../../../AGENTS.md).

## 1. Triết Lý Nghiên Cứu Trước Khi Viết Code (Research-First)
- **Tra cứu SSoT hiện có**: Trước khi tạo mới hàm hay thuật toán, bắt buộc kiểm tra các module dùng chung:
  - C++23: `src/core/common/` (`window_utils`, `math2d`, `string_utils`, `time_utils`, `toml_parser`, `input_action`, `logger`, `coordinate_transform`, `cli_options`).
  - Python 3.11: `src/common/` (`win32_input`, `vision_ocr`, `win32_window`, `win32_process`, `screen_capture`, `audio_feedback`, `item_types`, `logging_util`).
- **Zero Duplication**: Tuyệt đối cấm viết lại hàm toán học, đổi tọa độ, hoặc logic cửa sổ ở các module tính năng lẻ.

## 2. Quy Trình 4 Bước Triệt Tiêu Sửa Triệu Chứng (Mandatory 4-Step RCA)
Khi phát hiện lỗi hoặc dị thường (anomaly):
1. **Tái hiện & Truy vết (Trace)**: Cô lập điều kiện kích hoạt, vẽ call graph từ điểm lỗi ngược về nguồn dữ liệu bẩn.
2. **Xác định Bất biến bị Vi phạm**: Chỉ rõ quy tắc kiến trúc (`INV-*`) hoặc hợp đồng dữ liệu bị phá vỡ.
3. **Tái cấu trúc Tận gốc (Single Source of Logic)**: Sửa trực tiếp tại module hạt nhân nguồn, không chắp vá tại nơi hiển thị hoặc nơi nhận dữ liệu.
4. **Khóa chặn bằng Invariant Assertion**: Bổ sung `assert()`, `static_assert()` hoặc ngoại lệ chặn lỗi tái diễn.

## 3. Cấm Tuyệt Đối Sửa Điểm Lẻ (Strict Anti-Point-Fixing)
- Khi sửa một lỗi logic, bắt buộc grep quét toàn bộ workspace (cả C++ và Python) để tìm mọi vị trí có mô hình logic tương tự và xử lý đồng bộ.
- Cấm bypass điều kiện (`|| true`, `if (true)`), cấm comment assertion, cấm fake dữ liệu.

## 4. Cổng Nghiệm Thu Thực Nghiệm (Empirical DoD - Rule 5)
- **100% Authentic Data**: Mọi kiểm thử phải chạy trên dữ liệu thật từ client POE2 (RAM dump thật `captures/*_RAM.json`, ảnh thật `captures/*.png`, log thật `logs/Client.txt`).
- **Phòng ngừa hồi quy**: Mọi thuật toán thuần túy (Pathfinding, Coordinate Transform, Vitals Sanitizer) bắt buộc có Mock/Simulated Harness chạy 100% User Mode.
- **Trích xuất Raw CLI**: Báo cáo nghiệm thu bắt buộc đính kèm câu lệnh thực tế và log kết quả (số test PASS/FAIL, timing đo được).