@edupia-tutor/spec-driven-docs 0.14.7 → 0.14.8

package/skills/debug/SKILL.tmpl

@@ -4,259 +4,16 @@ description: Fix bug với full workflow (branch, test, commit), phân tích deb
 
 # Debug & Quality Skills — Fix Bug, Debug, Validate Traces
 
-Skill này xử lý: `/fix-bug` (full bug fix workflow), `/debug` (phân tích nhanh), và `/validate-traces` (check độ phủ traceability).
-
----
+Skill này xử lý `/fix-bug`, `/debug`, `/validate-traces`. Để **không lệch schema/flow**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command.
 
 ## /fix-bug — Full Bug Fix Workflow
+→ **Đọc và tuân theo `commands/fix-bug.md`** với cùng `$ARGUMENTS`.
+(Command lo: bug-type table theo platform · đọc `{BUG-ID}` report · regression test · build + push 2 tầng (umbrella) · BUG State `Open→Fixed`→`Closed` · đề xuất Lesson.)
 
-### Input
-
-Nhận: ticket ID (vd `PROJ-123`) hoặc một mô tả bug trực tiếp.
-
-### Phase 1 — Gather Information
-
-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
-
-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 (nếu có)?
-
-### Phase 2 — Root Cause Analysis
-
-{{include:steps/context-loader.md}}
-
-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 | Vị trí thường gặp | Cách kiểm tra |
-|----------|----------------|--------------|
-| 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:**
-
-```
-Root Cause Analysis — {TICKET_ID}:
-
-Bug: {description}
-Affected module: {module/service}
-Root cause: {specific technical analysis}
-Affected files:
-  - {file}: {what's wrong}
-
-Proposed fix:
-  - {file}: {what to change}
-
-Regression risk: Low / Medium / High
-  → Reason: {explanation}
-
-Proceed with fix? (Y/N)
-```
-
-Chờ user xác nhận.
-
-### Phase 3 — Implement Fix
-
-```bash
-git checkout -b fix/{TICKET_ID}-{short-description}
-```
-
-Áp dụng fix đúng như đã phân tích. Theo coding standards CLAUDE.md — đừng đưa thêm vi phạm mới.
-
-Thêm annotation traceability nếu file có `@trace.implements`:
-```
-// @trace.implements={UC-ID}-SC{N}
-// @trace.fixes={TICKET_ID}
-// @trace.root_cause={brief description}
-```
-
-### Phase 4 — Regression Test
-
-Sinh một regression test nếu chưa có:
-```
-// @trace.verifies={UC-ID}
-// @trace.regression={TICKET_ID}
-Test: "Regression {TICKET_ID}: {bug description}"
-  → Reproduce the exact bug scenario
-  → Assert the fix works correctly
-```
-
-Chạy test: `{TEST_COMMAND_FOR_CLASS}`
-
-Nếu test fail → debug và fix (tối đa 3 vòng).
-
-### Phase 5 — Build Verify
-
-```bash
-{BUILD_COMMAND}   # max 3 retries
-```
-
-### Phase 6 — Commit & Push
-
-```bash
-git add {changed files}
-git commit -m "fix({TICKET_ID}): {brief description}"
-git push -u origin fix/{TICKET_ID}-{slug}
-```
-
-### Output
-
-```
-/fix-bug Complete — {TICKET_ID}
-
-## Root Cause
-{analysis}
-
-## Changes
-- {file}: {what changed and why}
-
-## Regression Test
-✅ Added: {TestClass}.{method}
-✅ Build: SUCCESS
-
-## Branch
-fix/{TICKET_ID}-{slug}
-```
-
-{{include:steps/report-footer.md}}
-
----
-
-## /debug — Quick Debug Analysis
-
-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ì đó.
-
-**Khác `/fix-bug`**: Đây chỉ là phân tích, không full workflow, không cần ticket.
-
-### Input
-
-Dán một trong:
-1. Stack trace / error log
-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
-
-Đọc stack trace từ **dưới lên** — dòng `Caused by:` là root cause thật.
-
-```
-Caused by: {RealException}  ← start here
-  at {class}.{method}({file}:{line})  ← trace from here
-  ...
-  at {entrypoint}  ← where it was called from
-```
-
-### Common Error Patterns
-
-| Error | Nguyên nhân khả nghi | Hướng fix |
-|-------|-------------|---------------|
-| 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
-
-```
-Expected: {expected value}
-Actual  : {actual value}
-  at {test class}.{method}(line {N})
-```
-
-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
-
-```
-/debug Analysis
-
-## Error Encountered
-{description}
-
-## Root Cause
-{technical explanation}
-
-## Location in Code
-File: {path}
-Line: {line number if available}
-Layer: {Controller/Service/Repository/Test}
-
-## Suggested Fix
-{specific code change}
-
-## Related Rule
-See CLAUDE.md §{section} — {section name}
-
-## Next Step
-- To fully fix → run /fix-bug {TICKET_ID}
-- Just needed analysis → done here
-```
-
-{{include:steps/report-footer.md}}
-
----
-
-## /validate-traces — Traceability Coverage Matrix
-
-Check read-only độ phủ giữa spec, code, và test.
-
-### Input
-
-Nhận: tên domain hoặc UC-ID cụ thể.
-
-### Process
-
-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
-
-```
-/validate-traces — {domain}
-
-| UC-ID | SC | Spec | Code | Test | Status |
-|-------|----|------|------|------|--------|
-| {UC}-UC1 | SC1 | ✅ | ✅ {ControllerClass} | ✅ {TestClass} | synced |
-| {UC}-UC1 | SC2 | ✅ | ✅ {ControllerClass} | ❌ MISSING | gap |
-| {UC}-UC2 | SC1 | ✅ | ❌ MISSING | ❌ MISSING | gap |
-
-Gaps:
-  Missing code: [{UC-ID}-SC2, {UC-ID2}-SC1]
-  Missing tests: [{UC-ID}-SC1]
-  Drifted (spec changed, code not updated): [{list}]
-
-Recommendations:
-  - /generate-code {UC-ID} SC2
-  - /dev-gen-test {UC-ID}
-  - Re-run /generate-code {UC-ID} for drifted scenarios
-```
+## /debug — Phân tích nhanh
+→ **Đọc và tuân theo `commands/debug.md`** với cùng `$ARGUMENTS`.
+(Command lo: 4 path (stack trace / reproduce / test fail / câu hỏi code) · bảng lỗi theo từng platform/module · stack-trace đọc dưới-lên.)
 
-{{include:steps/report-footer.md}}
+## /validate-traces — Traceability Coverage
+→ **Đọc và tuân theo `commands/validate-traces.md`** với cùng `$ARGUMENTS`.
+(Command lo: đọc trace TSV 22 cột authoritative · tính OK/DRIFT/GAP/UNTRACKED + PRD/TECHDOC drift · sync `uc_status` ← `@trace.status` · aggregate dashboard.)