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

package/skills/test/SKILL.tmpl

@@ -1,10 +1,10 @@
 ---
-description: Generates unit and integration tests from BDD specs, runs the test suite and reports results, or dev-smoke-tests live API endpoints on a running service. Trigger when: "/dev-gen-test", "/dev-run-test", "/dev-smoke-test", "tạo test", "viết test", "chạy test", "generate tests", "run tests", "test kết quả", "smoke test", "test API", "kiểm tra endpoint đang chạy".
+description: Sinh unit và integration test từ BDD spec, chạy test suite và report kết quả, hoặc dev-smoke-test các API endpoint live trên service đang chạy. Trigger when: "/dev-gen-test", "/dev-run-test", "/dev-smoke-test", "tạo test", "viết test", "chạy test", "generate tests", "run tests", "test kết quả", "smoke test", "test API", "kiểm tra endpoint đang chạy".
 ---
 
 # Test Skills — Generate, Run & Smoke Test
 
-This skill handles three commands: `/dev-gen-test`, `/dev-run-test`, and `/dev-smoke-test`.
+Skill này xử lý ba lệnh: `/dev-gen-test`, `/dev-run-test`, và `/dev-smoke-test`.
 
 ---
 
@@ -15,13 +15,13 @@ This skill handles three commands: `/dev-gen-test`, `/dev-run-test`, and `/dev-s
 <!-- Directory: specs/*/*/bdd/*.feature — or pass UC-ID/class path as argument -->
 {{include:steps/gate.md}}
 
-Also read:
-- `.feature` file to understand expected behaviors
-- Find files to test: Controllers with `@trace.implements={UC-ID}`, Service implementations, Facade implementations (if applicable)
+Cũng đọc:
+- File `.feature` để hiểu các behavior kỳ vọng
+- Tìm file cần test: Controller có `@trace.implements={UC-ID}`, Service implementation, Facade implementation (nếu áp dụng)
 
 ### CHECKPOINT — Test Plan
 
-Before generating, present plan:
+Trước khi sinh, trình bày plan:
 
 ```
 Test Plan — {UC-ID}:
@@ -40,7 +40,7 @@ Total: {N} test classes, ~{M} test cases
 Proceed? (Y/N)
 ```
 
-Wait for confirmation.
+Chờ xác nhận.
 
 ### Generate
 
@@ -112,7 +112,7 @@ class {Resource}ControllerTest {
 
 ### File Placement
 
-Follow project test structure from CLAUDE.md. Typical:
+Theo cấu trúc test của dự án từ CLAUDE.md. Điển hình:
 ```
 src/test/{language}/{package}/
 ├── service/impl/{Resource}ServiceImplTest.{ext}
@@ -122,11 +122,11 @@ src/test/{language}/{package}/
 
 ### Self-Review Checklist
 
-- [ ] `@trace.verifies` tag on every test class
-- [ ] Every scenario in .feature has at least one test
-- [ ] Mock only the correct layer (no repo mocks in controller tests)
-- [ ] Test names follow `methodName_whenCondition_shouldOutcome` pattern
-- [ ] No debug print statements in tests
+- [ ] Tag `@trace.verifies` trên mỗi test class
+- [ ] Mỗi scenario trong .feature có ít nhất một test
+- [ ] Chỉ mock đúng layer (không mock repo trong controller test)
+- [ ] Test name theo pattern `methodName_whenCondition_shouldOutcome`
+- [ ] Không có debug print trong test
 
 ### Output
 
@@ -147,8 +147,8 @@ src/test/{language}/{package}/
 
 {{include:steps/context-loader.md}}
 
-Identify service/module from argument (UC-ID or service name).
-Read `conventions.test_command` from the loaded project context.
+Xác định service/module từ argument (UC-ID hoặc tên service).
+Đọc `conventions.test_command` từ project context đã nạp.
 
 ### Run
 
@@ -165,7 +165,7 @@ Read `conventions.test_command` from the loaded project context.
 
 ### Analyze Results
 
-#### When tests PASS
+#### Khi test PASS
 
 ```
 ✅ Tests passed
@@ -174,18 +174,18 @@ Read `conventions.test_command` from the loaded project context.
 - Duration: {X}s
 ```
 
-#### When tests FAIL — Debug Mode
+#### Khi test FAIL — Debug Mode
 
-Read stack trace and analyze:
+Đọc stack trace và phân tích:
 
-| Error Pattern | Common Cause | Suggested Fix |
+| Error Pattern | Nguyên nhân thường gặp | Suggested Fix |
 |---|---|---|
-| NullPointerException in test | Missing mock setup | Check `given(...)` setup for null dependency |
-| Bean/dependency not found | Missing mock/stub declaration | Add mock for missing dependency |
-| Expected 200 but got 403 | Missing auth setup in test | Add auth user/role to test context |
-| Expected 200 but got 400 | Request body fails validation | Check required fields in request DTO |
-| LazyInitializationException | Lazy collection accessed outside transaction | Add `@Transactional` on test or use eager fetch |
-| Mapper/mapper implementation not found | Code generator (e.g. MapStruct) not run | Run compile step before tests |
+| NullPointerException trong test | Thiếu setup mock | Kiểm tra setup `given(...)` cho dependency null |
+| Bean/dependency not found | Thiếu khai báo mock/stub | Thêm mock cho dependency thiếu |
+| Expected 200 but got 403 | Thiếu setup auth trong test | Thêm auth user/role vào test context |
+| Expected 200 but got 400 | Request body fail validation | Kiểm tra field bắt buộc trong request DTO |
+| LazyInitializationException | Lazy collection truy cập ngoài transaction | Thêm `@Transactional` trên test hoặc dùng eager fetch |
+| Mapper/mapper implementation not found | Code generator (vd MapStruct) chưa chạy | Chạy compile trước khi test |
 
 ### Output
 
@@ -212,32 +212,32 @@ Duration: {X}s
 
 ## /dev-smoke-test — Test Live API Endpoints
 
-Use when the service is **already running** to verify endpoints work correctly.
-Different from `/dev-run-test` (which runs unit/integration tests without a live server).
+Dùng khi service **đang chạy sẵn** để verify endpoint hoạt động đúng.
+Khác `/dev-run-test` (chạy unit/integration test không cần live server).
 
 ### Phase 1 — Find Service URL
 
 {{include:steps/context-loader.md}}
 
-Read `conventions.service_run` from the loaded project context to find port.
+Đọc `conventions.service_run` từ project context đã nạp để tìm port.
 Default: `http://localhost:8080`
 
-Check if service is running:
+Kiểm tra service đang chạy:
 ```bash
 curl -s http://localhost:{port}/health
 # or /actuator/health for Spring Boot
 ```
 
-If not running: "Service is not running. Start it with: `{RUN_COMMAND}` from your project root."
+Nếu chưa chạy: "Service is not running. Start it with: `{RUN_COMMAND}` from your project root."
 
 ### Phase 2 — Identify Endpoints
 
-From UC-ID → find Controller with `@trace.implements={UC-ID}`:
-- List: method, path, required auth/role
+Từ UC-ID → tìm Controller có `@trace.implements={UC-ID}`:
+- Liệt kê: method, path, auth/role bắt buộc
 
-### Phase 3 — Get Auth Token (if needed)
+### Phase 3 — Get Auth Token (nếu cần)
 
-If endpoints require auth, ask:
+Nếu endpoint yêu cầu auth, hỏi:
 ```
 This endpoint requires authentication. Options:
 1. Paste your Bearer token (from Postman / browser DevTools / test login)
@@ -261,17 +261,17 @@ curl -s -X POST "http://localhost:{port}/v1/{resource}" \
 
 ### Phase 5 — Interpret Results
 
-| Result | Meaning |
+| Result | Ý nghĩa |
 |--------|---------|
-| 200/201 + correct data | ✅ OK |
-| 200 + wrong data | ⚠️ Logic bug → use `/debug` |
-| 400 | Request body wrong → check required fields |
-| 401 | Token expired or wrong realm |
-| 403 | Wrong role → check auth config |
-| 500 + stacktrace | Server error → paste into `/debug` |
-| Connection refused | Service not running or wrong port |
-
-If errors in logs:
+| 200/201 + đúng data | ✅ OK |
+| 200 + sai data | ⚠️ Logic bug → dùng `/debug` |
+| 400 | Request body sai → kiểm tra field bắt buộc |
+| 401 | Token hết hạn hoặc sai realm |
+| 403 | Sai role → kiểm tra auth config |
+| 500 + stacktrace | Server error → dán vào `/debug` |
+| Connection refused | Service chưa chạy hoặc sai port |
+
+Nếu có lỗi trong log:
 ```bash
 tail -n 100 {LOG_FILE_PATH}
 ```

package/steps/capture-lesson.md

@@ -1,71 +1,71 @@
-# Capture Lesson — Record a Recurring Mistake as a Guardrail
+# Capture Lesson — Ghi lại lỗi lặp lại thành một Guardrail
 
-Reusable procedure to persist a "lesson" so the AI does not repeat a mistake in this project.
-Used by `/learn` (manual) and offered by `/review-code`, `/fix-bug`, `/debug` (auto).
+Quy trình tái sử dụng để lưu một "lesson" nhằm tránh AI lặp lại lỗi trong dự án này.
+Dùng bởi `/learn` (thủ công) và được đề xuất bởi `/review-code`, `/fix-bug`, `/debug` (tự động).
 
-> **Project memory, not model training.** A lesson is plain text injected into context at the
-> start of every command (context-loader Step 6.7). Functionally this stops the repeat — the AI
-> sees the guardrail before it generates. No model weights change.
+> **Bộ nhớ dự án, không phải huấn luyện model.** Một lesson là văn bản thuần được inject vào context ở
+> đầu mỗi lệnh (context-loader Bước 6.7). Về mặt chức năng, điều này chặn việc lặp lại — AI thấy
+> guardrail trước khi sinh nội dung. Không có trọng số model nào thay đổi.
 
-## L1 — Resolve the lessons file
+## L1 — Phân giải file lessons
 
-Resolve `lessons_path` in this order:
-1. `paths.lessons_file` from loaded context (may be service-overridden in umbrella mode, Step 1.6)
-2. Default `specs/domain-knowledge/lessons-learned.md` (single-service)
-3. In umbrella/service mode (when `service_root` is set) default `{service_root}/.agent/project-lessons.md`
+Phân giải `lessons_path` theo thứ tự sau:
+1. `paths.lessons_file` từ context đã nạp (có thể bị service override ở chế độ umbrella, Bước 1.6)
+2. Mặc định `specs/domain-knowledge/lessons-learned.md` (single-service)
+3. Ở chế độ umbrella/service (khi `service_root` được set) mặc định `{service_root}/.agent/project-lessons.md`
 
-## L2 — Build the lesson
+## L2 — Dựng lesson
 
-Gather these fields — from `$ARGUMENTS` (for `/learn`) or from the calling command's findings
-(for `/review-code`, `/fix-bug`, `/debug`):
+Thu thập các field sau — từ `$ARGUMENTS` (cho `/learn`) hoặc từ findings của lệnh gọi
+(cho `/review-code`, `/fix-bug`, `/debug`):
 
-| Field | Meaning |
+| Field | Ý nghĩa |
 |-------|---------|
-| `category` | one of: `code-gen` \| `bdd` \| `tech-docs` \| `tests` \| `prd` \| `general` |
-| `title` | short phrase naming the mistake |
-| `mistake` | concretely, what the AI did wrong |
-| `rule` | imperative correction — "Always …" / "Never …" — testable, not vague |
-| `scope` | where it applies: a domain, a file glob (e.g. `*Controller.*`), or `all` |
-| `source` | how captured: `/learn` \| `/review-code {UC-ID}` \| `/fix-bug {TICKET}` \| `/debug` |
+| `category` | một trong: `code-gen` \| `bdd` \| `tech-docs` \| `tests` \| `prd` \| `general` |
+| `title` | cụm từ ngắn đặt tên cho lỗi |
+| `mistake` | cụ thể, AI đã làm sai điều gì |
+| `rule` | câu sửa mệnh lệnh — "Luôn …" / "Không bao giờ …" — testable, không mơ hồ |
+| `scope` | phạm vi áp dụng: một domain, một file glob (vd `*Controller.*`), hoặc `all` |
+| `source` | cách ghi nhận: `/learn` \| `/review-code {UC-ID}` \| `/fix-bug {TICKET}` \| `/debug` |
 
-If `rule` is vague (e.g. "be careful"), rewrite it into a concrete, checkable instruction before saving.
+Nếu `rule` mơ hồ (vd "cẩn thận"), viết lại thành chỉ dẫn cụ thể, kiểm tra được trước khi lưu.
 
-## L3 — De-duplicate
+## L3 — Khử trùng lặp
 
-Read existing lessons in `lessons_path`. If one already covers the same mistake:
-- **Refine** that entry (tighten the Rule, widen/narrow Scope, bump Date, append the new Source) — do NOT add a duplicate.
+Đọc các lesson hiện có trong `lessons_path`. Nếu đã có một lesson cùng lỗi:
+- **Tinh chỉnh** entry đó (siết chặt Rule, mở rộng/thu hẹp Scope, cập nhật Date, thêm Source mới) — KHÔNG thêm bản trùng.
 
-Otherwise assign the next id `L-{NNN}` = (highest existing number + 1), zero-padded to 3 digits.
+Nếu không, gán id kế tiếp `L-{NNN}` = (số lớn nhất hiện có + 1), pad 0 đủ 3 chữ số.
 
-## L4 — Write
+## L4 — Ghi
 
-If `lessons_path` does not exist, create it with this header first:
+Nếu `lessons_path` chưa tồn tại, tạo file với header sau trước:
 
 ```markdown
 # Project Lessons — Learned Guardrails
 
-> Mistakes the AI must NOT repeat in this project. Loaded by context-loader at the start of
-> every command and treated as hard constraints (same priority as CLAUDE.md coding standards).
-> Add with /learn, or accept the prompt during /review-code, /fix-bug, /debug.
-> Commit this file so the whole team shares the guardrails.
+> Các lỗi AI KHÔNG được lặp lại trong dự án này. Được nạp bởi context-loader ở đầu
+> mỗi lệnh và coi như ràng buộc cứng (cùng mức ưu tiên với coding standards trong CLAUDE.md).
+> Thêm bằng /learn, hoặc chấp nhận prompt trong /review-code, /fix-bug, /debug.
+> Commit file này để cả team dùng chung guardrail.
 
-| Category | Applies to |
+| Category | Áp dụng cho |
 |----------|-----------|
-| code-gen | /generate-code output |
-| bdd | /generate-bdd output |
-| tech-docs | /generate-tech-docs output |
-| tests | /dev-gen-test output |
-| prd | /generate-prd, /refine-prd output |
-| general | every command |
+| code-gen | output của /generate-code |
+| bdd | output của /generate-bdd |
+| tech-docs | output của /generate-tech-docs |
+| tests | output của /dev-gen-test |
+| prd | output của /generate-prd, /refine-prd |
+| general | mọi lệnh |
 
 ---
 ```
 
-Insert the new lesson directly under the `---` separator (**newest first**), in this exact shape:
+Chèn lesson mới ngay dưới dấu phân cách `---` (**mới nhất lên đầu**), theo đúng dạng:
 
 ```markdown
 ### L-{NNN} — [{category}] {title}
-- **Date**: {today YYYY-MM-DD}
+- **Date**: {hôm nay YYYY-MM-DD}
 - **Scope**: {scope}
 - **Mistake**: {mistake}
 - **Rule**: {rule}
@@ -73,7 +73,7 @@ Insert the new lesson directly under the `---` separator (**newest first**), in
 
 ```
 
-## L5 — Confirm
+## L5 — Xác nhận
 
-Print: `📝 Lesson {id} recorded → {lessons_path}  ([{category}] {title})`
-Then remind: `Commit {lessons_path} so the team shares this guardrail.`
+In: `📝 Đã ghi lesson {id} → {lessons_path}  ([{category}] {title})`
+Rồi nhắc: `Commit {lessons_path} để cả team dùng chung guardrail này.`