--- name: ingest-data description: Use when taskType is "ingest-data" — PM/BrSE/Comtor ingesting customer communication (Backlog ticket/comment/Document/Wiki link, Jira link, SharePoint link, or pasted text) into AK-Docs/01.QnA/ logs. Covers fetching the source, classifying it into QnA-Log/Meetings-Log/Confirmations-Log, drafting the entry for self-review before Gate 2 opens the MR, and — auto right after Gate 2 — analyzing the entry to propose a PM-approved task list that gets created as real Backlog/Jira tickets. keywords: ingest data, comtor, brse, pm workflow, meeting minutes, qna log, confirmations log, backlog document, backlog wiki, sharepoint, gate 1, gate 2, gate 3, sinh task, tạo ticket --- # Ingest Data — Gate 1 (fetch/classify/draft) > **Vai trò:** PM · BrSE · Comtor. **Bối cảnh đầy đủ:** `docs/internal/PM Workflow_v1.0.md` (Flow A + Flow B). > Gate mechanics (khi nào chạy Gate 1 vs Gate 2) nằm ở `custom/templates/shared/gate-workflow.md` § "ingest-data Task Type". File này chỉ mô tả **cách làm** của Gate 1: fetch nguồn → phân loại → soạn draft. --- ## 1. Input được hỗ trợ | Input | Cách xử lý | |---|---| | Backlog ticket link (`/view/PROJ-N`) hoặc comment (`#comment-N`) | `ak fetch-links ""` → JSON `{ sourceType: "ticket" \| "comment", ... }` | | Backlog Document link (`/document/{id}`, `/alias/document/{id}`, hoặc share link mới `/document/{PROJECT_KEY}/e/{id}`) | `ak fetch-links ""` → JSON `{ sourceType: "document" \| "document-comment", ... }`. Đã xác nhận hoạt động live (2026-08-06) cho document body (`title`/`content`). ⚠️ Fetch comment trên Document (`document-comment`) vẫn chưa xác minh trên space thật — nếu lệnh trả lỗi HTTP 404 hoặc `content` rỗng, báo lại cho người dùng, đây là dấu hiệu endpoint/field cần điều chỉnh, không phải lỗi ở phía bạn. | | Backlog Wiki link (`/alias/wiki/{id}`) | `ak fetch-links ""` → JSON `{ sourceType: "wiki", ... }` | | Jira ticket/comment link | `ak fetch-links ""` → JSON `{ sourceType: "ticket" \| "comment", ... }` | | SharePoint link (`*.sharepoint.com`) | `ak fetch-links ""` → `{ sourceType: "unsupported", reason: "sharepoint-not-configured" }`. **Không có connector** (cần Microsoft Graph API + OAuth, xem PM Workflow doc "Vấn đề 4" — chưa làm POC). Hiển thị `message` trong JSON cho người dùng, và đề nghị: "Paste trực tiếp nội dung comment/tài liệu vào chat, mình sẽ dùng luôn." | | Plain text (paste trực tiếp trong chat, hoặc `ak use --manual`) | Dùng nguyên văn `description` từ `.aiflow/context/current.json` — không cần fetch gì thêm. | Nếu input không khớp bất kỳ dạng nào ở trên (`ak fetch-links` trả lỗi "Not a recognized... URL", exit code 1) → hỏi lại người dùng: link có đúng không, hoặc paste nội dung trực tiếp. --- ## 2. Phân loại — QnA-Log / Meetings-Log / Confirmations-Log | Log | Khi nào dùng | Nguồn điển hình | |---|---|---| | `QnA-Log.md` | Trao đổi hỏi-đáp thông thường với khách hàng | Backlog ticket/comment, Jira ticket/comment, SharePoint comment (paste text), text ngắn | | `Meetings-Log.md` | Tổng hợp nội dung 1 buổi họp (khách hoặc nội bộ) | Backlog Document, Backlog Wiki, text dài có cấu trúc (attendees/agenda/action items) | | `Confirmations-Log.md` | Mốc khách hàng **CHỐT chính thức** một spec/thay đổi | Bất kỳ nguồn nào, miễn nội dung là 1 xác nhận dứt điểm | **Heuristic gợi ý** (không phải luật cứng): - Nội dung có "họp", "meeting", "kickoff", "sprint review", danh sách người tham dự → nghiêng về **Meetings-Log**. - Nội dung có "confirm", "chốt", "OK approved", "đồng ý chính thức", đi kèm 1 quyết định rõ ràng, dứt điểm → nghiêng về **Confirmations-Log**. - Còn lại (hỏi/đáp, feedback, trao đổi qua lại chưa dứt điểm) → **QnA-Log**. > ⚠️ **Quy tắc phân biệt "confirm chính thức" vs "trao đổi thường" CHƯA được PM chốt** (xem `PM Workflow_v1.0.md` § "Vấn đề còn mở" #1). Khi không chắc content nào — **luôn hỏi lại người dùng** để chọn log đích, không tự quyết định âm thầm. Một khi PM ra quy tắc rõ ràng, cập nhật heuristic ở đây. --- ## 3. Template từng file (dùng đúng, không tự đổi cấu trúc) Cả 3 file nằm trong `AK-Docs/01.QnA/` (giữ nguyên tên thư mục hiện có — **không** đổi thành `01.Communications/` như một phương án còn đang chờ PM chốt trong `PM Workflow_v1.0.md`; nếu PM sau này quyết định đổi tên thư mục, đó là một task migration riêng). Nếu file đích **chưa tồn tại**, tạo file mới với đúng header dưới đây rồi mới append entry. ### 3.1 `QnA-Log.md` (file có sẵn — mở rộng thêm cột `Nguồn`) Header hiện tại của file có thể chỉ có 5 cột (`Date | Asked By | Question | Answer | Status`). Nếu vậy, **thêm cột `Nguồn` vào cuối** (sửa header + backfill các dòng cũ bằng `—`) rồi mới append dòng mới — để mọi entry từ giờ đều trace được nguồn gốc (yêu cầu traceability, xem PM Workflow doc § "Vấn đề 6"): ```markdown | Date | Asked By | Question | Answer | Status | Nguồn | |---|---|---|---|---|---| | 2026-08-04 | Khách hàng ABC | | | Pending / Answered | []() | ``` ### 3.2 `Meetings-Log.md` (file mới — tạo nếu chưa có) ```markdown # Meetings Log > Meeting minutes với khách hàng hoặc nội bộ — tổng hợp bởi Comtor/BrSE, PM approve tại nguồn trước khi ingest vào đây (xem Flow A trong PM Workflow_v1.0.md). --- ## [YYYY-MM-DD] | Trường | Giá trị | |---|---| | **Nguồn** | []() | | **functionId** | | | **Người tổng hợp** | | | **Người approve tại nguồn** | PM — | **Tóm tắt nội dung:** **Action items:** - [ ] --- ``` Mỗi lần ingest thêm 1 buổi họp mới → append 1 block `## [YYYY-MM-DD] ...` mới vào cuối file (chronological). ### 3.3 `Confirmations-Log.md` (file mới — tạo nếu chưa có) ```markdown # Confirmations Log > Mốc khách hàng CHỐT chính thức — trích từ Meeting Minutes (Backlog) hoặc comment "OK confirm" (SharePoint/Backlog). > ⚠️ Quy tắc phân biệt "confirm chính thức" vs "trao đổi thường" CHƯA được PM chốt (xem PM Workflow_v1.0.md § "Vấn đề còn mở" #1) — khi chưa rõ, hỏi lại người ingest trước khi ghi vào đây. | Date | Nội dung chốt | functionId | Nguồn | |---|---|---|---| | 2026-08-04 | | | []() | ``` --- ## 4. Soạn draft — hiển thị đầy đủ, không tóm tắt Sau khi fetch + phân loại, soạn đúng 1 entry theo template tương ứng ở mục 3, rồi hiển thị **nguyên văn** entry đó cho người dùng (không tóm tắt, không giấu bớt nội dung) kèm footer theo mẫu trong `gate-workflow.md` § "ingest-data" Gate 1 bước 5. **Không tự ghi file, không tự tạo branch** ở bước này — chỉ hiển thị draft trong hội thoại. Việc ghi file + branch + MR chỉ chạy ở Gate 2, sau khi người dùng gõ **APPROVED**. Nếu người dùng yêu cầu sửa (thêm/bớt ý, đổi log đích, sửa functionId...) → cập nhật lại draft, hiển thị lại toàn bộ, chờ APPROVED lại — lặp cho tới khi được duyệt. --- ## 5. Gate 3 — Sinh & Duyệt Task List, Tạo Ticket (auto, ngay sau Gate 2) > Implement "Vấn đề 5" trong `docs/internal/PM Workflow_v1.0.md`. **Trigger đã chốt: TỰ ĐỘNG** — chạy ngay tiếp theo Gate 2 (MR ingest vừa mở xong), không cần lệnh riêng, không chờ PM merge MR trước (merge MR là việc của PM ở luồng riêng, không block bước này). > Gate mechanics chi tiết (khi nào gọi lệnh nào) nằm ở `custom/templates/shared/gate-workflow.md` § "ingest-data Task Type" → GATE 3. File này chỉ mô tả **cách phân tích và đề xuất**. ### 5.1 Bước 1 — Đọc lại entry + điều tra phạm vi ảnh hưởng Đọc lại đúng entry vừa ghi ở Gate 2 (Meetings-Log.md / QnA-Log.md / Confirmations-Log.md — nguyên văn nội dung người dùng đã input ở Gate 1, không phải bản tóm tắt). Sau đó: 1. Xác định `functionId` liên quan (đã có trong entry, hoặc `general`). 2. Đọc source code + tài liệu hiện có liên quan đến `functionId` đó (UC Spec ở `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/`, code trong repo source, `AK-Docs/04.Coding/00.Overview/_Index.md`) để hiểu **hệ thống hiện tại đang làm gì**, từ đó đánh giá nội dung mới vừa ingest tác động tới đâu. 3. Nếu nội dung có Action items rõ ràng trong template Meeting Minutes (mục 3.2) — đây là gợi ý mạnh cho danh sách task, không bỏ qua. ### 5.2 Bước 2 — Quyết định: có cần task hay không **Không phải mọi entry đều sinh ra task.** Trước khi đề xuất bất kỳ task nào, tự hỏi: nội dung này có yêu cầu một hành động cụ thể (thay đổi spec, code, test, tài liệu...) hay chỉ là thông tin tham khảo/FYI (cập nhật tiến độ, thông tin không đổi hành vi hệ thống, trả lời một câu hỏi đã đóng)? - **Chỉ là tham khảo** → hiển thị: `ℹ️ Nội dung này không phát sinh task — chỉ lưu làm tài liệu tham khảo. Gate 3 kết thúc.` rồi chạy `ak gate 3 skip --ticket [ticket-id] --reason "<1 câu lý do>"` (không cần `ak gate 3 start` trước) và dừng, không hỏi thêm. Việc này đóng gate đúng cách — dashboard (ai-flow-ex) hiển thị "⏭ Gate 3 skipped — \" thay vì để task treo mãi ở trạng thái "sẵn sàng chạy Gate 3". - **Có hành động cụ thể** → tiếp tục Bước 3. Khi không chắc (ví dụ nội dung vừa có FYI vừa có 1 ý cần sửa code) — nghiêng về đề xuất task cho phần cần hành động, bỏ qua phần FYI, không tự bịa task cho phần không rõ. **Riêng khi nguồn là `Confirmations-Log`** (khách hàng CHỐT chính thức 1 thay đổi requirement) — đây là trường hợp dễ đề xuất thiếu task nhất nếu chỉ dựa vào Action items viết sẵn trong nội dung (vd chỉ thấy 1 bug fix được nêu tên, bỏ sót toàn bộ phần spec/testcase phát sinh từ chính rule vừa chốt). Trước khi sang Bước 3, tự chạy qua đủ checklist tối thiểu sau — không hiển thị checklist này cho PM, chỉ dùng để tự rà soát không bỏ sót: 1. **UC Spec** — functionId này đã có UC Spec chưa, và rule vừa chốt đã phản ánh trong Spec chưa? Chưa → task `spec`. 2. **System Requirement** — chỉ cần nếu có task `coding` theo sau (Gate 1 coding sẽ tự chặn nếu System Requirement thiếu/lệch version, xem `CLAUDE.md` pre-check) → task `system-requirement`. 3. **Impact analysis** — thay đổi có đủ phức tạp/rủi ro (ảnh hưởng nhiều module/feature khác, hoặc PM cần thấy effort/scope trước khi giao việc) để cần 1 tài liệu đánh giá riêng, tách khỏi Gate 1 coding không? Cần → task `impact-analysis`. 4. **Coding** — có thay đổi hành vi hệ thống cần code không? Cần → task `coding` (tách thành nhiều task nhỏ nếu phạm vi lớn, mỗi task 1 title riêng). 5. **Data migration/backfill** — rule mới có áp dụng hồi tố lên dữ liệu đã tồn tại không (khác với chỉ áp dụng từ nay về sau)? Có → thêm 1 task `coding` **riêng** cho việc migration/backfill, không gộp chung với task coding chính (2 rủi ro/effort khác nhau, cần review riêng). 6. **Create/Update testcase** — cần → task `test`. 7. **Execute test** — cần → task `execute-test`. Không phải mục nào cũng luôn có (case rule chỉ áp dụng tương lai thì mục 5 = không cần) — nhưng phải đi qua đủ 7 mục và có lý do trước khi kết luận không cần, không bỏ qua mục nào chỉ vì nội dung entry không viết thành Action item rõ ràng. ### 5.3 Bước 3 — Đề xuất danh sách task Mỗi task gồm: | Trường | Ghi chú | |---|---| | `type` | `spec` (tạo/update UC Spec) · `system-requirement` (tạo/update System Requirement) · `impact-analysis` (đánh giá phạm vi ảnh hưởng, tách riêng khỏi Gate 1 coding) · `coding` (bao gồm cả migration/backfill, tách task riêng nếu cần) · `test` (tạo/update testcase) · `execute-test` (thực thi testcase có sẵn) · `other` (update tài liệu không thuộc BA/QA/Dev, vd Rules) | | `title` | Ngắn, hành động rõ (vd "Cập nhật flow OTP theo feedback khách — tăng thời hạn 30s → 90s") | | `track` | BA / Dev / QA / Analyst — để PM biết ai sẽ nhận task này | | `description` | Theo đúng template mục 6.1 `PM Workflow_v1.0.md`: | Mỗi `type` map thẳng vào 1 task type có sẵn khi người nhận chạy `ak use TICKET-XXX` (không cần Gate workflow mới — xem `scripts/use.js` cho danh sách đầy đủ): | `type` task | Task type chọn ở `ak use` | |---|---| | `spec` | 📋 Create Spec | | `system-requirement` | 📐 Create System Requirement | | `impact-analysis` | 📊 Impact Analysis | | `coding` | 🐛 Bug Fix / ✨ Feature / 🔄 Refactor (tuỳ nội dung task) | | `test` | ✅ Create TestCase | | `execute-test` | ▶️ Execute Test | | `other` | Không map task type nào — tuỳ nội dung, người nhận tự xử lý ngoài Gate workflow | ```text ## Nội dung task [Mô tả task do AI đề xuất] ## Nguồn tham chiếu - Văn bản gốc: []() - Log AK-Docs: AK-Docs/01.QnA/[QnA-Log.md | Meetings-Log.md | Confirmations-Log.md] (entry ngày ) ``` Riêng task `type: "spec"` — thêm 2 mục bắt buộc theo mục 6.1, và **hỏi PM xin link hồ sơ cam kết thay đổi nếu chưa có sẵn** (không tự suy luận): ```text ## Tổng quan nội dung thay đổi [Tóm tắt: thay đổi gì, vì sao thay đổi] ## Nguồn tham chiếu - Hồ sơ cam kết thay đổi: []() - Log AK-Docs (nếu có): AK-Docs/01.QnA/Meetings-Log.md (entry ngày ) ``` Hiển thị toàn bộ danh sách cho PM xem — đủ cả `type`/`title`/`track`/`description`, không tóm tắt. ### 5.4 Bước 4 — PM review, sửa trực tiếp trong hội thoại PM có thể **thêm / sửa / xoá từng task** ngay trong lượt review này (không phải chỉ APPROVED/reject toàn bộ) — cập nhật lại danh sách theo đúng yêu cầu, hiển thị lại toàn bộ, lặp lại cho tới khi PM hài lòng. Task nào type là `spec` mà thiếu "Nguồn tham chiếu" (hồ sơ cam kết thay đổi) → coi như chưa đủ điều kiện, phải hỏi PM bổ sung trước khi cho vào vòng xác nhận tạo ticket ở Bước 5. ### 5.5 Bước 5 — Điểm dừng xác nhận tạo ticket Hỏi đúng 1 câu, không tự thêm `--yes`: ```text Danh sách task như trên (N task) — đồng ý tạo trên [Backlog/Jira]? ``` - Xác định target `backlog`/`jira` theo đúng adapter của ticket/document gốc đã ingest ở Gate 1/2 (Backlog → target backlog; Jira → target jira). Nếu nguồn là pasted text/SharePoint (không rõ adapter) → hỏi PM muốn tạo trên hệ thống nào. - **KHÔNG ĐỒNG Ý** → dừng, để PM tự chỉnh sửa rồi yêu cầu lại (quay lại Bước 4). - **ĐỒNG Ý** → sang Bước 6. ### 5.6 Bước 6 — Xác định project đích Check LOCAL trước, chỉ hỏi khi thật sự chưa biết (Vấn đề 5.1): 1. Backlog: kiểm tra `BACKLOG_DEFAULT_PROJECT_ID` đã lưu chưa (chạy `ak backlog-projects --json`, đọc field `defaultProjectId`). Jira: `ak jira-projects --json`, đọc `defaultProjectKey`. 2. Đã có → dùng luôn, hiển thị rõ cho PM biết đang dùng project nào + nguồn (đã lưu từ lần trước). 3. Chưa có → hiển thị danh sách project vừa fetch được, PM chọn 1 → lưu lại bằng `ak backlog-set-default-project ` hoặc `ak jira-set-default-project ` — để lần sau không hỏi lại. ### 5.6b Bước 6b — Ticket cha (chỉ hỏi khi danh sách có ≥ 2 task) Nếu danh sách chỉ có 1 task, không có gì để gộp — coi `parentTicket.mode = "none"` và bỏ qua bước này. Nếu ≥ 2 task, hỏi đúng 1 câu: ```text Gộp N task này dưới 1 ticket cha? 1. Tạo mới ticket cha 2. Dùng ticket cha có sẵn — cho biết ticket ID 3. Không cần ticket cha ``` - **(1)** → hỏi PM 1 tiêu đề ngắn cho ticket cha (gợi ý: dùng lại "Tổng quan nội dung thay đổi" đã soạn cho task `spec` ở Bước 3, nếu có; không có thì tự tóm tắt 1 câu). `parentTicket = { "mode": "create", "title": "...", "description": "..." }`. - **(2)** → PM nhập ticket ID có sẵn. `parentTicket = { "mode": "existing", "existingId": "" }`. Việc xác minh ticket đó có tồn tại thật diễn ra ở Bước 7 (khi gọi `ak tasks create-tickets`) — không tự coi là đúng trước khi có kết quả lệnh. - **(3)** → `parentTicket = { "mode": "none" }`. ⚠️ **Chưa xác minh trên instance thật:** liên kết cha-con cần Backlog project đã bật tính năng phân cấp issue (Subtasking), hoặc Jira project hỗ trợ field `parent` trực tiếp (rõ nhất với project dạng team-managed; company-managed có thể cần issue type `Subtask` riêng — chưa test). Nếu Bước 7 báo lỗi `parent-create-failed`/`parent-not-found`, hoặc 1 task con lỗi do gán parent thất bại — hiển thị nguyên lỗi cho PM, hỏi PM muốn: thử lại với ticket cha khác, tiếp tục tạo các ticket con không gắn parent (`mode: "none"`), hay dừng lại để PM xử lý cấu hình Backlog/Jira trước. ### 5.7 Bước 7 — Tạo ticket 1. Ghi danh sách task đã duyệt ra 1 file JSON tạm (vd `.aiflow/tmp/tasks-[ticketId].json`), đúng shape mà `ak tasks create-tickets` đọc (xem `scripts/ticket-writer.js`): ```json { "target": "backlog", "parentTicket": { "mode": "create", "title": "...", "description": "..." }, "tasks": [ { "type": "coding", "title": "...", "description": "..." } ] } ``` `parentTicket` lấy nguyên từ kết quả Bước 6b (bỏ field này hoặc `{"mode": "none"}` nếu không gộp ticket cha). 2. Chạy `ak tasks create-tickets --json`. 3. Đọc kết quả JSON trả về: - `{"error":"missing-write-credentials", "field": "...", "message": "..."}` → **đây không phải lỗi hệ thống** — hiển thị đúng `message` cho PM, hỏi PM nhập giá trị key ngay trong hội thoại (dùng luôn khung chat làm nơi PM "nhập & submit"), nhận giá trị → chạy `ak credentials set ""` → chạy lại bước 2 (retry đúng 1 lần; nếu vẫn lỗi, báo PM key có thể sai/chưa đủ quyền, không tự thử lại vô hạn). - `{"error":"missing-project", ...}` → quay lại Bước 6 (chưa xác định được project). - `{"error":"parent-not-found", "message": "..."}` → ticket cha PM cung cấp ở Bước 6b (2) không tồn tại/không đọc được — báo PM, quay lại Bước 6b để nhập ID khác hoặc chọn phương án khác. - `{"error":"parent-create-failed", "message": "..."}` → tạo ticket cha thất bại (thường do project chưa hỗ trợ phân cấp issue) — hiển thị nguyên lỗi, hỏi PM có muốn tạo lại không gắn ticket cha (`mode: "none"`) hay dừng lại. - Thành công (`ok: true`) → mỗi task có `ticketId` + `url` riêng, có thêm `parent` (ticket cha vừa tạo/dùng, nếu có); task nào `ok: false` (lỗi phía Backlog/Jira, vd thiếu field) → báo rõ cho PM, các task khác đã tạo vẫn giữ nguyên (không rollback). ### 5.8 Bước 8 — Ghi ngược liên kết + đóng Gate 1. Append vào cuối đúng entry gốc (Meetings-Log/QnA-Log/Confirmations-Log) 1 dòng, kèm ticket cha nếu có: ```text → Tasks created: TICKET-100 (parent), TICKET-101 (coding), TICKET-102 (test) ``` Việc sửa file này đi qua đúng branch đang dùng ở Gate 2 (không tạo MR riêng — gộp vào cùng thay đổi, hoặc nếu MR đã mở/merge thì tạo 1 commit nhỏ tiếp theo trên cùng branch/1 MR mới tuỳ trạng thái branch lúc đó). 2. Hiển thị tổng kết: ```text ✅ GATE 3 DONE — Đã tạo N/N ticket trên [Backlog/Jira]: - Ticket cha: TICKET-100 — (bỏ dòng này nếu không gộp ticket cha) - TICKET-101 (coding) — - TICKET-102 (test) — → Dev/QA chạy `ak use TICKET-XXX` trên từng ticket để bắt đầu Gate tương ứng (Coding/QA workflow hiện có). ``` 3. Run: `ak gate 3 approved --ticket [ticket-id]`. > **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` khi bắt đầu Bước 1 (bỏ qua nếu Bước 2 kết luận không cần task — không start gate cho trường hợp "chỉ tham khảo"). Run `ak gate 3 approved --ticket [ticket-id]` khi Bước 8 xong, HOẶC `ak gate 3 skip --ticket [ticket-id] --reason "..."` khi Bước 2 kết luận không cần task (thay cho việc không đóng gate — xem Bước 2).