@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.1

package/commands/fix-bug.tmpl

@@ -1,9 +1,9 @@
-# /fix-bug — Full Bug Fix Workflow
+# /fix-bug — Workflow Fix Bug đầy đủ
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a ticket ID (e.g., `PROJ-123`), a **filed bug `{BUG-ID}`** (a `{paths.bug_reports_dir}/{BUG-ID}.md` from `/report-bug` — e.g. a QC product-gap), or a bug description from `$ARGUMENTS`. If a `{BUG-ID}` is given, resolve & read that report for spec context; otherwise proceed to context loading.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một ticket ID (vd `PROJ-123`), một **bug đã file `{BUG-ID}`** (một `{paths.bug_reports_dir}/{BUG-ID}.md` từ `/report-bug` — vd một QC product-gap), hoặc một mô tả bug từ `$ARGUMENTS`. Nếu cho `{BUG-ID}`, phân giải & đọc report đó để lấy spec context; ngược lại tiếp tục sang context loading.*
 
 ## Context
 {{include:steps/context-loader.md}}
@@ -11,69 +11,69 @@
 ---
 
 ## Phase 1 — Gather Info
-If a `{BUG-ID}` was given: read `{paths.bug_reports_dir}/{BUG-ID}.md` for the spec context, AC violated, expected-vs-actual, and the suggested layer — use it as the bug details (no need to re-ask).
-If ticket: fetch details (or ask user to paste).
-If no ticket / BUG-ID — CHECKPOINT:
-1. Where does the bug occur? (module, endpoint, flow)
-2. Steps to reproduce?
+Nếu cho `{BUG-ID}`: đọc `{paths.bug_reports_dir}/{BUG-ID}.md` để lấy spec context, AC bị vi phạm, expected-vs-actual, và layer gợi ý — dùng làm chi tiết bug (không cần hỏi lại).
+Nếu ticket: fetch chi tiết (hoặc nhờ user dán).
+Nếu không có ticket / BUG-ID — CHECKPOINT:
+1. Bug xảy ra ở đâu? (module, endpoint, flow)
+2. Các bước tái hiện?
 3. Expected vs Actual?
 4. Error log / stack trace?
 
 ## Phase 2 — Root Cause Analysis
 
-Use `active_module` from context to select the relevant table.
+Dùng `active_module` từ context để chọn bảng liên quan.
 
-### If `platform_type = backend`
+### Nếu `platform_type = backend`
 
 #### java-spring / golang / dotnet / php-laravel
 
-| Bug Type | Common Location | How to Check |
+| Bug Type | Vị trí thường gặp | Cách kiểm tra |
 |----------|----------------|--------------|
-| Wrong response data | Mapping layer | Check field mapping, DTO conversions |
-| 400 Bad Request | Input validation | Check DTO constraints / validators |
-| 401 Unauthorized | Auth filter | Check token config, filter order |
-| 403 Forbidden | Auth config | Check role-based access rules |
-| 404 Not Found | Repository query | Check find method, ID types |
-| N+1 Query | Data access | Check for missing JOIN FETCH / eager load |
-| Null Pointer | Optional not handled | Check Optional.orElseThrow, null guards |
-| Transaction rollback | Missing @Transactional | Check transaction scope, propagation |
-| Stale cache | Missing eviction | Check cache invalidation triggers |
-| Type mismatch | Filter / specification | Check field types in predicates |
+| Wrong response data | Mapping layer | Kiểm tra field mapping, DTO conversion |
+| 400 Bad Request | Input validation | Kiểm tra DTO constraint / validator |
+| 401 Unauthorized | Auth filter | Kiểm tra token config, thứ tự filter |
+| 403 Forbidden | Auth config | Kiểm tra rule role-based access |
+| 404 Not Found | Repository query | Kiểm tra find method, kiểu ID |
+| N+1 Query | Data access | Kiểm tra thiếu JOIN FETCH / eager load |
+| Null Pointer | Optional chưa xử lý | Kiểm tra Optional.orElseThrow, null guard |
+| Transaction rollback | Thiếu @Transactional | Kiểm tra transaction scope, propagation |
+| Stale cache | Thiếu eviction | Kiểm tra trigger cache invalidation |
+| Type mismatch | Filter / specification | Kiểm tra kiểu field trong predicate |
 
 #### context-engineering (AI/LLM pipelines)
 
-| Bug Type | Common Location | How to Check |
+| Bug Type | Vị trí thường gặp | Cách kiểm tra |
 |----------|----------------|--------------|
-| Wrong pipeline output | Prompt template | Check prompt content; verify variables are substituted correctly |
-| Missing context in output | Context assembly | Verify all required context blocks are included and non-empty |
-| Schema validation failure | Output parser | Compare raw LLM output vs expected schema; add stricter output instructions |
-| Flaky / non-deterministic results | LLM temperature | Check temperature setting; use fixed seed/mock in tests |
-| API rate limit errors | LLM client | Implement backoff; check quota usage in provider dashboard |
-| Token limit exceeded | Prompt assembly | Reduce context size; add chunking strategy |
+| Wrong pipeline output | Prompt template | Kiểm tra nội dung prompt; verify biến được substitute đúng |
+| Missing context in output | Context assembly | Verify mọi context block bắt buộc có mặt và không rỗng |
+| Schema validation failure | Output parser | So raw LLM output vs schema kỳ vọng; thêm output instruction chặt hơn |
+| Flaky / non-deterministic results | LLM temperature | Kiểm tra temperature; dùng fixed seed/mock trong test |
+| API rate limit errors | LLM client | Implement backoff; kiểm tra quota trên dashboard provider |
+| Token limit exceeded | Prompt assembly | Giảm kích thước context; thêm chiến lược chunking |
 
-### If `platform_type = web-frontend`
+### Nếu `platform_type = web-frontend`
 
-| Bug Type | Common Location | How to Check |
+| Bug Type | Vị trí thường gặp | Cách kiểm tra |
 |----------|----------------|--------------|
-| Wrong data displayed | State / store | Check state update logic, selector |
-| UI not re-rendering | Missing reactive dep | Check deps array, state immutability |
-| API data not loading | HTTP client / hook | Check network tab, error handler |
-| 401 on API call | Auth token | Check token refresh, header injection |
-| Form not submitting | Validation / handler | Check form state, required fields, errors |
-| Route not found | Router config | Check route definition, lazy import |
-| Build / type error | TypeScript types | Compare type definitions vs actual API shape |
+| Wrong data displayed | State / store | Kiểm tra logic update state, selector |
+| UI not re-rendering | Thiếu reactive dep | Kiểm tra deps array, state immutability |
+| API data not loading | HTTP client / hook | Kiểm tra network tab, error handler |
+| 401 on API call | Auth token | Kiểm tra token refresh, header injection |
+| Form not submitting | Validation / handler | Kiểm tra form state, field bắt buộc, error |
+| Route not found | Router config | Kiểm tra route definition, lazy import |
+| Build / type error | TypeScript types | So type definition vs shape API thực tế |
 
-### If `platform_type = mobile`
+### Nếu `platform_type = mobile`
 
-| Bug Type | Common Location | How to Check |
+| Bug Type | Vị trí thường gặp | Cách kiểm tra |
 |----------|----------------|--------------|
-| Screen shows stale data | State / BLoC / ViewModel | Check event dispatched, state emitted correctly |
-| Crash on navigation | Route param missing | Check params passed, null safety |
-| API call not firing | Repository / service layer | Add log in repo method, check network |
-| UI not reflecting state | Widget not observing stream | Check `BlocBuilder` / `StateObserver` setup |
-| Crash on app resume | Lifecycle handler | Check `onResume` / `viewDidAppear` logic |
-| Auth token expired | Token refresh logic | Check refresh flow, token storage |
-| Permission denied | OS permission | Check runtime permission request code |
+| Screen shows stale data | State / BLoC / ViewModel | Kiểm tra event dispatch, state emit đúng |
+| Crash on navigation | Thiếu route param | Kiểm tra param truyền, null safety |
+| API call not firing | Repository / service layer | Thêm log trong repo method, kiểm tra network |
+| UI not reflecting state | Widget không observe stream | Kiểm tra setup `BlocBuilder` / `StateObserver` |
+| Crash on app resume | Lifecycle handler | Kiểm tra logic `onResume` / `viewDidAppear` |
+| Auth token expired | Token refresh logic | Kiểm tra refresh flow, token storage |
+| Permission denied | OS permission | Kiểm tra code request runtime permission |
 
 CHECKPOINT — Root Cause Report:
 ```
@@ -87,13 +87,13 @@ Proceed? (Y/N)
 
 ## Phase 3 — Fix
 
-*Umbrella mode: the buggy code lives in the **service submodule** resolved at context-loader Step 1.6 — create the branch and run every git/build step from **inside** `{service_root}`. Single-service: omit the `cd`.*
+*Umbrella mode: code lỗi sống trong **service submodule** phân giải ở context-loader Bước 1.6 — tạo branch và chạy mọi bước git/build từ **trong** `{service_root}`. Single-service: bỏ `cd`.*
 
 ```bash
 cd {service_root}                              # umbrella: the service submodule; single-service: omit
 git checkout -b fix/{TICKET_ID}-{description}
 ```
-Apply fix. Add trace annotation if file has `@trace.implements`:
+Áp dụng fix. Thêm trace annotation nếu file có `@trace.implements`:
 ```
 @trace.fixes={TICKET_ID}
 @trace.root_cause={brief description}
@@ -105,53 +105,53 @@ Apply fix. Add trace annotation if file has `@trace.implements`:
 // @trace.regression={TICKET_ID}
 Test: "Regression {TICKET_ID}: {bug description}"
 ```
-Run test. If fail → debug and fix (max 3 iterations).
+Chạy test. Nếu fail → debug và fix (tối đa 3 vòng).
 
-## Phase 5 — Build & Commit (2-layer push in umbrella mode)
+## Phase 5 — Build & Commit (push 2 tầng ở umbrella mode)
 ```bash
-{conventions.build_command}   # max 3 retries — runs inside {service_root} in umbrella mode
-# Tầng 1 — push the fix branch in the service submodule (where the code lives):
+{conventions.build_command}   # tối đa 3 retry — chạy trong {service_root} ở umbrella mode
+# Tầng 1 — push fix branch trong service submodule (nơi code sống):
 git add {files}
 git commit -m "fix({TICKET_ID}): {description}"
-git push -u origin fix/{TICKET_ID}-{slug}      # then open a PR into the service's tracked branch
+git push -u origin fix/{TICKET_ID}-{slug}      # rồi mở PR vào branch được track của service
 ```
-> **Umbrella mode — Tầng 2 (bump umbrella pointer):** the umbrella records a *commit* of the service
-> submodule, not a branch. After the fix-branch PR **merges** into the service's tracked branch, bump
-> the pointer so teammates pulling the umbrella don't hit "commit not found":
+> **Umbrella mode — Tầng 2 (bump umbrella pointer):** umbrella ghi một *commit* của service
+> submodule, không phải branch. Sau khi PR fix-branch **merge** vào branch được track của service, bump
+> pointer để đồng đội pull umbrella không gặp "commit not found":
 > ```bash
 > cd -                                          # back to umbrella root
 > git add {service_root} && git commit -m "chore: bump {service_root} pointer (fix {TICKET_ID})"
 > git push
 > ```
-> Single-service mode: no umbrella pointer — Tầng 1 is the whole push. Full rule: Sync & Update §4.4 (commit 2 tầng).
+> Single-service mode: không có umbrella pointer — Tầng 1 là toàn bộ push. Quy tắc đầy đủ: Sync & Update §4.4 (commit 2 tầng).
 
-## Phase 5.5 — Close the bug report (if fixing a filed `{BUG-ID}`)
+## Phase 5.5 — Đóng bug report (nếu fix một `{BUG-ID}` đã file)
 
-*Skip if the target was a plain ticket/description (no `{BUG-ID}` file).*
+*Bỏ qua nếu target là ticket/mô tả thường (không có file `{BUG-ID}`).*
 
-After the fix is committed, update `{paths.bug_reports_dir}/{BUG-ID}.md`:
-- Set `State` → `🟡 Fixed` and append a short **Resolution** (root cause + commit/PR link).
-- It is **not** `Closed` yet — QC owns verification: when `/qc-run-test` re-runs and `qc_status`
-  for the linked SC flips to `pass`, it becomes `🟢 Closed` (and `qc_owner`/`qc_blocked_by` clear).
-- Commit the updated report to the spec repo (same 2-layer push as `/report-bug`) so the PO/PM
-  "waiting-on" view reflects it on `/sync`.
+Sau khi fix được commit, cập nhật `{paths.bug_reports_dir}/{BUG-ID}.md`:
+- Set `State` → `🟡 Fixed` và thêm một **Resolution** ngắn (root cause + link commit/PR).
+- Nó **chưa** `Closed` — QC sở hữu verification: khi `/qc-run-test` chạy lại và `qc_status`
+  của SC liên kết flip thành `pass`, nó thành `🟢 Closed` (và `qc_owner`/`qc_blocked_by` clear).
+- Commit report đã cập nhật vào spec repo (cùng push 2 tầng như `/report-bug`) để view
+  "waiting-on" của PO/PM phản ánh nó trên `/sync`.
 
-This is the only write `/fix-bug` makes to the feedback area — it still fixes **code** only,
-never edits PRD/BDD (spec changes are PO/Dev per BUG_FLOW Case 2–4).
+Đây là lần ghi duy nhất `/fix-bug` làm tới khu feedback — nó vẫn chỉ fix **code**,
+không bao giờ sửa PRD/BDD (thay đổi spec là việc PO/Dev theo BUG_FLOW Case 2–4).
 
-## Phase 6 — Offer to Record a Lesson (optional)
+## Phase 6 — Đề xuất ghi Lesson (tuỳ chọn)
 
-If the root cause was a **mistake the AI made during generation and could repeat**
-(e.g. it generated code that skipped a layer, missed a null guard, used a wrong pattern —
-NOT an external cause like a third-party outage or bad input data), ask:
+Nếu root cause là một **lỗi AI gây ra khi sinh và có thể lặp lại**
+(vd nó sinh code skip layer, thiếu null guard, dùng sai pattern —
+KHÔNG phải nguyên nhân bên ngoài như outage third-party hay input data sai), hỏi:
 
 ```
-This root cause looks like a repeatable AI mistake.
-Record it as a project lesson so it isn't generated again? (Y/N)
+Root cause này trông như một lỗi AI lặp lại.
+Ghi nó thành project lesson để không bị sinh lại? (Y/N)
 ```
 
-If `Y` → run the capture procedure below with `source=/fix-bug {TICKET_ID}`, an appropriate
-`category` (usually `code-gen`), and `scope` = the affected domain or file glob.
+Nếu `Y` → chạy quy trình capture bên dưới với `source=/fix-bug {TICKET_ID}`, một
+`category` phù hợp (thường `code-gen`), và `scope` = domain hoặc file glob bị ảnh hưởng.
 
 {{include:steps/capture-lesson.md}}
 
@@ -160,12 +160,12 @@ If `Y` → run the capture procedure below with `source=/fix-bug {TICKET_ID}`, a
 {{include:steps/report-footer.md}}
 
 ```
-/fix-bug Complete — {TICKET_ID}
+/fix-bug Hoàn tất — {TICKET_ID}
 Root Cause: {analysis}
 Changes: {list}
 ✅ Regression test added | ✅ Build: SUCCESS
-{🐞 BUG-{id} → State: Fixed (pushed) — Closed after /qc-run-test re-verify pass | if fixing a filed bug}
-{📝 Lesson L-NNN recorded (if captured)}
+{🐞 BUG-{id} → State: Fixed (pushed) — Closed sau khi /qc-run-test re-verify pass | nếu fix một bug đã file}
+{📝 Lesson L-NNN recorded (nếu đã capture)}
 Branch: fix/{TICKET_ID}-{slug}
-Next: Create PR and link to ticket. {QC: re-run /qc-run-test {UC-ID} to verify + close the bug | if applicable}
+Next: Tạo PR và link tới ticket. {QC: chạy lại /qc-run-test {UC-ID} để verify + đóng bug | nếu áp dụng}
 ```