@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/commands/fix-bug.tmpl

@@ -1,197 +0,0 @@
-# /fix-bug — Workflow Fix Bug đầy đủ
-
-## Gate
-{{include:steps/gate.md}}
-
-*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}}
-
----
-
-## Phase 1 — Gather Info
-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
-
-Dùng `active_module` từ context để chọn bảng liên quan.
-
-### Nếu `platform_type = backend`
-
-#### java-spring / golang / dotnet / php-laravel
-
-| Bug Type | Vị trí thường gặp | Cách kiểm tra |
-|----------|----------------|--------------|
-| 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 | Vị trí thường gặp | Cách kiểm tra |
-|----------|----------------|--------------|
-| 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 |
-
-### Nếu `platform_type = web-frontend`
-
-| Bug Type | Vị trí thường gặp | Cách kiểm tra |
-|----------|----------------|--------------|
-| 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ế |
-
-### Nếu `platform_type = mobile`
-
-| Bug Type | Vị trí thường gặp | Cách kiểm tra |
-|----------|----------------|--------------|
-| 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:
-```
-Bug: {description} | Module: {name}
-Root cause: {analysis}
-Affected files: {list}
-Proposed fix: {what to change}
-Regression risk: Low / Medium / High
-Proceed? (Y/N)
-```
-
-## Phase 3 — Fix
-
-*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}
-```
-Áp dụng fix. Thêm trace annotation nếu file có `@trace.implements`:
-```
-@trace.fixes={BUG-ID nếu fix từ một bug report đã file · else TICKET_ID}
-@trace.root_cause={brief description}
-```
-*(Ưu tiên `{BUG-ID}`: khi fix bắt nguồn từ `/report-bug` thì thường **không có** ticket ID nào, và `{BUG-ID}` mới là thứ trace ngược được về spec context + AC bị vi phạm.)*
-
-## Phase 4 — Regression Test
-```
-// @trace.verifies={UC-ID}
-// @trace.regression={TICKET_ID}
-Test: "Regression {TICKET_ID}: {bug description}"
-```
-Chạy test. Nếu fail → debug và fix (tối đa 3 vòng).
-
-## Phase 4.5 — Cập nhật sổ trace
-
-*Bỏ qua nếu fix không chạm SC nào có row trace (vd fix hạ tầng/config).*
-
-Đây là lệnh **duy nhất** sinh test mà trước đây không ghi sổ — hệ quả: `test_count` under-report vĩnh viễn (SC đứng `GAP` dù vừa có regression test, rồi `/validate-traces` khuyên `/dev-gen-test` → dev sinh test trùng), và `dev_selftest` giữ `pass` cũ **trên code đã đổi**.
-
-Định vị sổ platform `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — `{platform}` = platform của code vừa fix; không rõ → glob `{UC-ID}-*.tsv` tìm sổ nào chứa `sc_id` đó, khớp nhiều sổ → **hỏi** (cùng luật với `/report-bug` Step 5.5).
-
-Với mỗi SC mà regression test phủ (theo `@trace.verifies` của test vừa viết):
-
-| Cột | Giá trị |
-|---|---|
-| `test_count` | **+=** số test method regression vừa thêm (cộng dồn, không ghi đè) |
-| `test_classes` | **append** tên test class/describe mới, giữ nguyên tên cũ |
-| `dev_selftest` | `not_run` — code vừa đổi nên tín hiệu self-test cũ hết hiệu lực |
-| `dev_selftest_at` | `—` |
-| `last_updated` | hôm nay `YYYY-MM-DD` |
-
-Giữ nguyên mọi cột khác. Đặc biệt:
-- **KHÔNG** đụng `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` — QC sở hữu; `/qc-run-test` sẽ flip khi re-verify (và chính nó đóng `{BUG-ID}` → `🟢 Closed`).
-- **KHÔNG** đụng `spec_ver`/`gen_ver` — fix bug **không** đổi spec, nên không được tạo tín hiệu DRIFT giả.
-
-Rồi làm mới panel mirror:
-{{include:steps/trace-mirror.md}}
-```bash
-{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}      # rồi mở PR vào branch được track của service
-```
-> **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: 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 — Đóng bug report (nếu fix một `{BUG-ID}` đã file)
-
-*Bỏ qua nếu target là ticket/mô tả thường (không có file `{BUG-ID}`).*
-
-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`.
-
-Đâ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 — Đề xuất ghi Lesson (tuỳ chọn)
-
-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:
-
-```
-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)
-```
-
-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}}
-
-## Output
-
-{{include:steps/report-footer.md}}
-
-```
-/fix-bug Hoàn tất — {TICKET_ID}
-Root Cause: {analysis}
-Changes: {list}
-✅ Regression test added | ✅ Build: SUCCESS
-{Trace: {UC-ID}-{platform}.tsv updated — test_count +{n}, dev_selftest → not_run | nếu có chạm row trace}
-{🐞 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: /dev-run-test {UC-ID}  ← dev_selftest vừa bị reset về not_run, chạy để lấy lại tín hiệu xanh
-      Rồi 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}
-```