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

package/skills/debug/SKILL.tmpl

@@ -1,10 +1,10 @@
 ---
-description: Fixes bugs with full workflow (branch, test, commit), performs quick debug analysis of errors or unexpected behavior, or validates traceability coverage between specs and code. Trigger when: "/fix-bug", "/debug", "/validate-traces", "fix bug", "sửa bug", "debug lỗi", "phân tích lỗi", "tại sao lỗi này", "validate traces", "kiểm tra traceability", "coverage matrix", "trace drift".
+description: Fix bug với full workflow (branch, test, commit), phân tích debug nhanh các lỗi hoặc hành vi bất ngờ, hoặc kiểm chứng độ phủ traceability giữa spec và code. Trigger when: "/fix-bug", "/debug", "/validate-traces", "fix bug", "sửa bug", "debug lỗi", "phân tích lỗi", "tại sao lỗi này", "validate traces", "kiểm tra traceability", "coverage matrix", "trace drift".
 ---
 
 # Debug & Quality Skills — Fix Bug, Debug, Validate Traces
 
-This skill handles: `/fix-bug` (full bug fix workflow), `/debug` (quick analysis), and `/validate-traces` (traceability coverage check).
+Skill này xử lý: `/fix-bug` (full bug fix workflow), `/debug` (phân tích nhanh), và `/validate-traces` (check độ phủ traceability).
 
 ---
 
@@ -12,42 +12,42 @@ This skill handles: `/fix-bug` (full bug fix workflow), `/debug` (quick analysis
 
 ### Input
 
-Accept: ticket ID (e.g. `PROJ-123`) or a direct bug description.
+Nhận: ticket ID (vd `PROJ-123`) hoặc một mô tả bug trực tiếp.
 
 ### Phase 1 — Gather Information
 
-If ticket ID provided:
-- Fetch ticket details if Jira/issue tracker is connected
-- Otherwise ask user to paste: title, steps to reproduce, expected vs actual
+Nếu cho ticket ID:
+- Fetch chi tiết ticket nếu Jira/issue tracker được kết nối
+- Ngược lại nhờ user dán: title, các bước tái hiện, expected vs actual
 
-If no ticket:
-**CHECKPOINT** — Ask:
-1. Where does the bug occur? (service, endpoint, flow)
-2. Steps to reproduce?
+Nếu không có ticket:
+**CHECKPOINT** — Hỏi:
+1. Bug xảy ra ở đâu? (service, endpoint, flow)
+2. Các bước tái hiện?
 3. Expected vs Actual behavior?
-4. Error log / stack trace (if any)?
+4. Error log / stack trace (nếu có)?
 
 ### Phase 2 — Root Cause Analysis
 
 {{include:steps/context-loader.md}}
 
-Trace through layers (from CLAUDE.md architecture):
-1. Identify the service/module from the failing endpoint/feature
-2. Read relevant code files, layer by layer
-3. Match against common bug patterns:
+Trace qua các layer (từ kiến trúc CLAUDE.md):
+1. Xác định service/module từ endpoint/feature đang lỗi
+2. Đọc các file code liên quan, từng layer
+3. Đối chiếu với các bug pattern thường gặp:
 
-| Bug Type | Common Location | How to Check |
+| Bug Type | Vị trí thường gặp | Cách kiểm tra |
 |----------|----------------|--------------|
-| Wrong response data | Data mapping layer | Check field mapping, DTO conversions |
-| 400 Bad Request | Input validation | Check DTO constraints, required fields |
-| 403 Forbidden | Auth configuration | Check role-based access rules |
-| 404 Not Found | Repository query | Check find method, ID types |
-| Slow query / N+1 | Data access layer | Check for missing JOIN FETCH or batch loading |
-| Null Pointer | Missing null checks, optional not handled | Check Optional.orElseThrow usage |
-| Transaction rollback | Missing/wrong transaction scope | Check @Transactional on service methods |
-| Stale cache | Missing cache eviction after write | Check cache invalidation on write operations |
-| Type mismatch in query | Filter/specification code | Check field types in query predicates |
-| Cross-service timeout | External service call | Check URL config, fallback behavior |
+| Wrong response data | Data mapping layer | Kiểm tra field mapping, DTO conversion |
+| 400 Bad Request | Input validation | Kiểm tra DTO constraint, field bắt buộc |
+| 403 Forbidden | Auth configuration | Kiểm tra rule role-based access |
+| 404 Not Found | Repository query | Kiểm tra find method, kiểu ID |
+| Slow query / N+1 | Data access layer | Kiểm tra thiếu JOIN FETCH hoặc batch loading |
+| Null Pointer | Thiếu null check, Optional chưa xử lý | Kiểm tra dùng Optional.orElseThrow |
+| Transaction rollback | Thiếu/sai transaction scope | Kiểm tra @Transactional trên service method |
+| Stale cache | Thiếu cache eviction sau write | Kiểm tra cache invalidation khi write |
+| Type mismatch in query | Code filter/specification | Kiểm tra kiểu field trong query predicate |
+| Cross-service timeout | Lời gọi external service | Kiểm tra URL config, hành vi fallback |
 
 **CHECKPOINT — Root Cause Report:**
 
@@ -69,7 +69,7 @@ Regression risk: Low / Medium / High
 Proceed with fix? (Y/N)
 ```
 
-Wait for user confirmation.
+Chờ user xác nhận.
 
 ### Phase 3 — Implement Fix
 
@@ -77,9 +77,9 @@ Wait for user confirmation.
 git checkout -b fix/{TICKET_ID}-{short-description}
 ```
 
-Apply the fix exactly as analyzed. Follow CLAUDE.md coding standards — do not introduce new violations.
+Áp dụng fix đúng như đã phân tích. Theo coding standards CLAUDE.md — đừng đưa thêm vi phạm mới.
 
-Add traceability annotation if the file has `@trace.implements`:
+Thêm annotation traceability nếu file có `@trace.implements`:
 ```
 // @trace.implements={UC-ID}-SC{N}
 // @trace.fixes={TICKET_ID}
@@ -88,7 +88,7 @@ Add traceability annotation if the file has `@trace.implements`:
 
 ### Phase 4 — Regression Test
 
-Generate a regression test if one doesn't exist:
+Sinh một regression test nếu chưa có:
 ```
 // @trace.verifies={UC-ID}
 // @trace.regression={TICKET_ID}
@@ -97,9 +97,9 @@ Test: "Regression {TICKET_ID}: {bug description}"
   → Assert the fix works correctly
 ```
 
-Run the test: `{TEST_COMMAND_FOR_CLASS}`
+Chạy test: `{TEST_COMMAND_FOR_CLASS}`
 
-If test fails → debug and fix (max 3 iterations).
+Nếu test fail → debug và fix (tối đa 3 vòng).
 
 ### Phase 5 — Build Verify
 
@@ -140,21 +140,21 @@ fix/{TICKET_ID}-{slug}
 
 ## /debug — Quick Debug Analysis
 
-Use when: IDE shows an error, test fails unexpectedly, behavior is strange, or you need to understand why code does something.
+Dùng khi: IDE hiện lỗi, test fail bất ngờ, hành vi lạ, hoặc bạn cần hiểu vì sao code làm gì đó.
 
-**Different from `/fix-bug`**: This is analysis only, no full workflow, no ticket required.
+**Khác `/fix-bug`**: Đây chỉ là phân tích, không full workflow, không cần ticket.
 
 ### Input
 
-Paste one of:
+Dán một trong:
 1. Stack trace / error log
-2. Test failure output
-3. File path + description of unexpected behavior
-4. A specific question about a code snippet
+2. Output test fail
+3. File path + mô tả hành vi bất ngờ
+4. Một câu hỏi cụ thể về code snippet
 
 ### Stack Trace Analysis
 
-Read stack trace from **bottom up** — the `Caused by:` line is the real root cause.
+Đọc stack trace từ **dưới lên** — dòng `Caused by:` là root cause thật.
 
 ```
 Caused by: {RealException}  ← start here
@@ -165,18 +165,18 @@ Caused by: {RealException}  ← start here
 
 ### Common Error Patterns
 
-| Error | Likely Cause | Fix Direction |
+| Error | Nguyên nhân khả nghi | Hướng fix |
 |-------|-------------|---------------|
-| NullPointerException | Accessing field on null object; Optional not handled | Check Optional.orElseThrow, null guards |
-| ClassCastException | Wrong type assumption; incorrect generic usage | Check type at assignment/return point |
-| OutOfMemoryError | Loading too much data; memory leak | Add pagination, check collection sizes |
-| StackOverflowError | Infinite recursion | Find recursive call with no base case |
-| Connection refused | Dependency service not running | Check config URLs, start dependent service |
-| Authentication/401 | Token expired, wrong config, missing header | Verify token, check auth config |
-| Permission denied/403 | Wrong role in request or misconfigured access rules | Check auth annotations and role config |
-| Database constraint violation | Duplicate key, missing FK, null in NOT NULL column | Check data and constraint definitions |
-| Serialization error | Circular reference, unmapped field | Check DTO/mapper configuration |
-| Test assertion mismatch | Wrong mock setup or wrong expected value | Re-read mock setup and assertion logic |
+| NullPointerException | Truy cập field trên object null; Optional chưa xử lý | Kiểm tra Optional.orElseThrow, null guard |
+| ClassCastException | Giả định sai kiểu; dùng generic không đúng | Kiểm tra type ở điểm assignment/return |
+| OutOfMemoryError | Load quá nhiều data; memory leak | Thêm pagination, kiểm tra kích thước collection |
+| StackOverflowError | Đệ quy vô hạn | Tìm recursive call không có base case |
+| Connection refused | Dependency service chưa chạy | Kiểm tra config URL, khởi động service phụ thuộc |
+| Authentication/401 | Token hết hạn, sai config, thiếu header | Verify token, kiểm tra auth config |
+| Permission denied/403 | Sai role trong request hoặc access rule cấu hình sai | Kiểm tra auth annotation và role config |
+| Database constraint violation | Trùng key, thiếu FK, null trong cột NOT NULL | Kiểm tra data và định nghĩa constraint |
+| Serialization error | Circular reference, field chưa map | Kiểm tra config DTO/mapper |
+| Test assertion mismatch | Sai mock setup hoặc sai giá trị expected | Đọc lại mock setup và logic assertion |
 
 ### Test Failure Analysis
 
@@ -186,10 +186,10 @@ Actual  : {actual value}
   at {test class}.{method}(line {N})
 ```
 
-1. What is the gap between Expected and Actual?
-2. Trace to the exact test line
-3. Is the mock setup correct? (`given(...).willReturn(...)`)
-4. Is the assertion logically correct?
+1. Gap giữa Expected và Actual là gì?
+2. Trace tới đúng dòng test
+3. Mock setup đúng chưa? (`given(...).willReturn(...)`)
+4. Assertion có đúng logic không?
 
 ### Output
 
@@ -224,18 +224,18 @@ See CLAUDE.md §{section} — {section name}
 
 ## /validate-traces — Traceability Coverage Matrix
 
-Read-only check of coverage between specs, code, and tests.
+Check read-only độ phủ giữa spec, code, và test.
 
 ### Input
 
-Accept: domain name or specific UC-ID.
+Nhận: tên domain hoặc UC-ID cụ thể.
 
 ### Process
 
-1. **Read .feature files** → collect all SC-IDs for the domain/UC
-2. **Scan controller files** → find `@trace.implements` tags
-3. **Scan test files** → find `@trace.verifies` tags
-4. **Read `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`** → check for drift (scenario text changed since last code gen)
+1. **Đọc file .feature** → gom tất cả SC-ID cho domain/UC
+2. **Quét file controller** → tìm tag `@trace.implements`
+3. **Quét file test** → tìm tag `@trace.verifies`
+4. **Đọc `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`** → check drift (text scenario đổi từ lần gen code trước)
 
 ### Output