diff --git a/.agent/workflows/docs-edit-vi-en.md b/.agent/workflows/docs-edit-vi-en.md index 53229de1..3fc41f3b 100644 --- a/.agent/workflows/docs-edit-vi-en.md +++ b/.agent/workflows/docs-edit-vi-en.md @@ -31,6 +31,49 @@ README.md (service root) --- +## ⚠️ AGENT EXECUTION GUIDELINES (CRITICAL) + +> **Đọc phần này TRƯỚC KHI thực thi workflow!** + +### Quy Trình Thực Thi Đúng + +**LUÔN tuân theo các bước sau theo thứ tự:** + +1. **Đọc TOÀN BỘ workflow specification** từ đầu đến cuối +2. **Kiểm tra current state** của service documentation +3. **So sánh current state với workflow requirements** (đặc biệt chú ý Bước 2 về filename convention) +4. **Xác định gaps/issues dựa trên workflow** - KHÔNG dựa trên assumption hay kinh nghiệm từ project khác +5. **Thực hiện changes** theo đúng workflow specification +6. **Validate theo workflow checklist** (Bước 7) + +### ❌ Common Mistakes to Avoid + +**Mistake #1: Không đọc kỹ workflow trước khi thực thi** +- ❌ BAD: Thấy files `KIEN-TRUC.md` → Giả định sai → Đổi tên thành `kien-truc.md` +- ✅ GOOD: Đọc Bước 2 → Thấy "cùng tên file tiếng Anh" → Giữ nguyên `ARCHITECTURE.md` + +**Mistake #2: Dựa vào assumptions từ các workflows/projects khác** +- ❌ BAD: "Tôi nghĩ Vietnamese files nên dùng Vietnamese filenames" +- ✅ GOOD: "Workflow nói rõ: Both EN/VI use SAME English filenames" + +**Mistake #3: Bỏ qua validation checklist** +- ❌ BAD: Làm xong → Notify user ngay +- ✅ GOOD: Làm xong → Check Bước 7 → Đảm bảo đúng spec → Notify user + +### ✅ Pre-Flight Checklist + +Trước khi bắt đầu thực thi, hãy xác nhận: + +- [ ] Đã đọc toàn bộ workflow specification? +- [ ] Đã hiểu rõ filename convention ở Bước 2? +- [ ] Đã kiểm tra current state của documentation? +- [ ] Đã so sánh current state với workflow requirements? +- [ ] Đã xác định chính xác những gì CẦN thay đổi (không phải GIẢ ĐỊNH)? + +**Nếu có bất kỳ câu trả lời "No" nào → Quay lại đọc workflow!** + +--- + ## Bước 1: Xác Định Cấu Trúc Hiện Tại / Identify Current Structure **Actions:** @@ -284,7 +327,6 @@ See detailed documentation in [docs/en/](docs/en/) or [docs/vi/](docs/vi/). - [ ] All Mermaid diagrams have dark color palette - [ ] No syntax errors in Mermaid - [ ] Links work correctly -- [ ] **Filename is UPPERCASE** (e.g., `ARCHITECTURE.md`, `README.md`) **For each VI file:** - [ ] No English text (except technical terms) @@ -292,39 +334,49 @@ See detailed documentation in [docs/en/](docs/en/) or [docs/vi/](docs/vi/). - [ ] All Mermaid diagrams have dark color palette - [ ] Mermaid structure matches EN version - [ ] Links work correctly -- [ ] **Filename is kebab-case Vietnamese** (e.g., `kien-truc.md`, `gioi-thieu.md`) -- [ ] **No diacritics in filename** (e.g., `kien-truc` not `kiến-trúc`) -- [ ] **No underscores**, only hyphens ### 7.2 Structure Checklist - [ ] `docs/en/` exists with all required files - [ ] `docs/vi/` exists with mirror files (same count) - [ ] Service root `README.md` links to both EN/VI -- [ ] **EN filenames are UPPERCASE** (e.g., `ARCHITECTURE.md`, `API.md`) -- [ ] **VI filenames are lowercase kebab-case** (e.g., `kien-truc.md`, `api.md`) -- [ ] Files match mapping table (e.g., `ARCHITECTURE.md` ↔ `kien-truc.md`) +- [ ] **Both EN and VI folders use SAME English filenames** (e.g., `ARCHITECTURE.md` in both) +- [ ] File count matches between EN/VI directories (e.g., 4 files in EN = 4 files in VI) -### 7.3 Filename Mapping Validation +### 7.3 Filename Convention Validation + +**✅ CORRECT Convention (as per Bước 2):** + +Both `docs/en/` and `docs/vi/` use **SAME English filenames**: -**Verify EN/VI pairs:** ```bash -# Example pairs that should exist -docs/en/README.md ↔ docs/vi/gioi-thieu.md -docs/en/ARCHITECTURE.md ↔ docs/vi/kien-truc.md -docs/en/API.md ↔ docs/vi/api.md -docs/en/WHATSAPP_SETUP.md ↔ docs/vi/cai-dat-whatsapp.md +docs/en/ARCHITECTURE.md ↔ docs/vi/ARCHITECTURE.md ✅ +docs/en/API.md ↔ docs/vi/API.md ✅ +docs/en/README.md ↔ docs/vi/README.md ✅ +docs/en/TWITTER_SETUP.md ↔ docs/vi/TWITTER_SETUP.md ✅ ``` -**Common mistakes:** -- ❌ `docs/vi/ARCHITECTURE.md` (English name in VI folder) -- ❌ `docs/vi/KIEN-TRUC.md` (uppercase in VI folder) -- ❌ `docs/vi/kien_truc.md` (underscore instead of hyphen) -- ❌ `docs/vi/kiến-trúc.md` (using diacritics) -- ✅ `docs/vi/kien-truc.md` (correct!) +**❌ INCORRECT (Common mistakes):** +```bash +# Mistake 1: Using Vietnamese filenames in VI folder +docs/en/ARCHITECTURE.md ↔ docs/vi/kien-truc.md ❌ WRONG! +docs/en/TWITTER_SETUP.md ↔ docs/vi/cai-dat-twitter.md ❌ WRONG! -### 7.3 Mermaid Validation +# Mistake 2: Case inconsistency +docs/en/ARCHITECTURE.md ↔ docs/vi/architecture.md ❌ WRONG! + +# Correct approach +docs/en/ARCHITECTURE.md ↔ docs/vi/ARCHITECTURE.md ✅ CORRECT! +``` + +**Why this convention?** +- ✅ Easier to find corresponding files +- ✅ No need to remember two naming schemes +- ✅ Better cross-reference in documentation +- ✅ Simpler maintenance + +### 7.4 Mermaid Validation ```bash # Optional: validate Mermaid syntax using mermaid-cli @@ -371,13 +423,13 @@ services/my-service-net/ ├── README.md (links to docs/en and docs/vi) └── docs/ ├── en/ - │ ├── README.md (English only, dark Mermaid) - │ ├── ARCHITECTURE.md (English only, dark Mermaid) - │ └── API.md (English only) + │ ├── README.md (English content) + │ ├── ARCHITECTURE.md (English content) + │ └── API.md (English content) └── vi/ - ├── gioi-thieu.md (Vietnamese only, dark Mermaid) - ├── kien-truc.md (Vietnamese only, dark Mermaid) - └── api.md (Vietnamese only) + ├── README.md (Vietnamese content, same filename!) + ├── ARCHITECTURE.md (Vietnamese content, same filename!) + └── API.md (Vietnamese content, same filename!) ``` ---