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

package/commands/debug.tmpl

@@ -1,206 +1,206 @@
-# /debug — Quick Debug Analysis
+# /debug — Phân tích Debug nhanh
 
-Use for: IDE errors, test failures, strange behavior, or "why does this code do X?"
-Different from `/fix-bug`: analysis only, no full workflow, no ticket needed.
+Dùng cho: lỗi IDE, test fail, hành vi lạ, hoặc "tại sao code này làm X?"
+Khác `/fix-bug`: chỉ phân tích, không full workflow, không cần ticket.
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is user-provided input (stack trace, test failure output, file path + description, or code question). No file discovery needed — go straight to context loading.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là input người dùng cung cấp (stack trace, output test fail, file path + mô tả, hoặc câu hỏi code). Không cần tìm file — đi thẳng sang context loading.*
 
 ## Context
 {{include:steps/context-loader.md}}
 
 ---
 
-## Step 1 — Classify debug type
+## Step 1 — Phân loại loại debug
 
-After loading context, display this prompt and wait for the user's choice:
+Sau khi nạp context, hiện prompt này và chờ user chọn:
 
 ```
 DEBUG SESSION
 ──────────────────────────────────────────────────────────────
-  What's your situation?
+  Tình huống của bạn?
 
-  1  I already have a stack trace / error log  → paste it
-  2  I need to reproduce the error first       → show me the run command
-  3  A test is failing                         → I'll run tests, then paste output
-  4  Code question (no runtime needed)         → ask away
+  1  Tôi đã có stack trace / error log  → dán nó
+  2  Tôi cần reproduce lỗi trước        → chỉ tôi lệnh run
+  3  Một test đang fail                 → tôi sẽ chạy test, rồi dán output
+  4  Câu hỏi về code (không cần runtime) → hỏi luôn
 ──────────────────────────────────────────────────────────────
-Enter 1 / 2 / 3 / 4:
+Nhập 1 / 2 / 3 / 4:
 ```
 
-Wait for the user's choice, then follow the corresponding path below.
+Chờ user chọn, rồi theo path tương ứng bên dưới.
 
 ---
 
-### Path 1 — Already have error output
+### Path 1 — Đã có error output
 
-Ask:
+Hỏi:
 ```
-Paste your stack trace / error log below:
+Dán stack trace / error log của bạn bên dưới:
 ```
 
-Wait for input, then proceed to [Stack Trace Analysis](#stack-trace-analysis).
+Chờ input, rồi sang [Stack Trace Analysis](#stack-trace-analysis).
 
 ---
 
-### Path 2 — Need to reproduce first
+### Path 2 — Cần reproduce trước
 
-Display the run command from `conventions.service_run` in `project-context.yaml`:
+Hiện lệnh run từ `conventions.service_run` trong `project-context.yaml`:
 
 ```
-Start your service first:
+Khởi động service trước:
 
   {conventions.service_run}
 
-(If you use Docker: `docker compose up -d`, then verify with `docker compose ps`)
+(Nếu dùng Docker: `docker compose up -d`, rồi verify với `docker compose ps`)
 
-Once the service is running:
-  1. Trigger the behavior that causes the error
-  2. Copy the full stack trace or error log
-  3. Paste it here
+Khi service đang chạy:
+  1. Trigger hành vi gây lỗi
+  2. Copy full stack trace hoặc error log
+  3. Dán vào đây
 
-Waiting for your error output...
+Đang chờ error output của bạn...
 ```
 
-Wait for the user to paste the error, then proceed to [Stack Trace Analysis](#stack-trace-analysis).
+Chờ user dán lỗi, rồi sang [Stack Trace Analysis](#stack-trace-analysis).
 
-If `conventions.service_run` is not set → show:
+Nếu `conventions.service_run` chưa set → hiện:
 ```
-⚠️  service_run is not configured in .agent/project-context.yaml.
-    Add it so this command can show the correct start command:
+⚠️  service_run chưa được cấu hình trong .agent/project-context.yaml.
+    Thêm nó để lệnh này hiện đúng lệnh khởi động:
 
     conventions:
       service_run: "mvn spring-boot:run"   # or: npm run dev / go run . / etc.
 ```
-Then ask the user to start the service manually and paste the error when ready.
+Rồi nhờ user khởi động service thủ công và dán lỗi khi sẵn sàng.
 
 ---
 
-### Path 3 — Test is failing
+### Path 3 — Test đang fail
 
-Display the test command from `conventions.test_command` in `project-context.yaml`:
+Hiện lệnh test từ `conventions.test_command` trong `project-context.yaml`:
 
 ```
-Run your tests first:
+Chạy test của bạn trước:
 
   {conventions.test_command}
 
-Once the run finishes, paste the full test failure output here.
+Khi chạy xong, dán full output test fail vào đây.
 
-Waiting...
+Đang chờ...
 ```
 
-Wait for the user to paste the failure output, then proceed to [Test Failure Analysis](#test-failure-analysis).
+Chờ user dán output fail, rồi sang [Test Failure Analysis](#test-failure-analysis).
 
-If `conventions.test_command` is not set → show:
+Nếu `conventions.test_command` chưa set → hiện:
 ```
-⚠️  test_command is not configured in .agent/project-context.yaml.
-    Add it so this command can show the correct test command:
+⚠️  test_command chưa được cấu hình trong .agent/project-context.yaml.
+    Thêm nó để lệnh này hiện đúng lệnh test:
 
     conventions:
       test_command: "mvn test"   # or: npm test / go test ./... / etc.
 ```
-Then ask the user to run tests manually and paste the output when ready.
+Rồi nhờ user chạy test thủ công và dán output khi sẵn sàng.
 
 ---
 
-### Path 4 — Code question
+### Path 4 — Câu hỏi code
 
-Ask:
+Hỏi:
 ```
-Describe your question or paste the code snippet you're asking about:
+Mô tả câu hỏi của bạn hoặc dán code snippet bạn đang hỏi:
 ```
 
-Wait for input, then answer directly using loaded project context (architecture rules, layer order, coding standards from CLAUDE.md).
+Chờ input, rồi trả lời trực tiếp dùng project context đã nạp (quy tắc kiến trúc, thứ tự layer, coding standards từ CLAUDE.md).
 
 ---
 
 ## Stack Trace Analysis
 
-Read from **bottom up** — `Caused by:` is the real root cause:
+Đọc từ **dưới lên** — `Caused by:` là root cause thật:
 ```
-Caused by: {RealException}  ← start here
+Caused by: {RealException}  ← bắt đầu ở đây
   at {class}.{method}({file}:{line})
 ```
 
 ## Common Error Patterns
 
-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
 
-| Error | Likely Cause | Fix Direction |
+| Error | Nguyên nhân khả nghi | Hướng fix |
 |-------|-------------|---------------|
-| NullPointerException | Null object access; Optional not handled | Check Optional.orElseThrow, null guards |
-| ClassCastException | Wrong type assumption | Check type at assignment/return |
-| OutOfMemoryError | Loading too much data | Add pagination |
-| StackOverflowError | Infinite recursion | Find recursive call with no base case |
-| Connection refused | Dependency not running | Check config URLs / start service |
-| 401 Unauthorized | Token expired, wrong config | Verify token, check auth config |
-| 403 Forbidden | Wrong role | Check auth annotations |
-| DB constraint violation | Duplicate key, null in NOT NULL | Check data and constraints |
-| Serialization error | Circular reference | Check DTO/mapper config |
-| Test assertion mismatch | Wrong mock or wrong expected | Re-read mock setup |
+| NullPointerException | Truy cập object null; Optional chưa xử lý | Kiểm tra Optional.orElseThrow, null guard |
+| ClassCastException | Giả định sai kiểu | Kiểm tra type ở assignment/return |
+| OutOfMemoryError | Load quá nhiều data | Thêm pagination |
+| StackOverflowError | Đệ quy vô hạn | Tìm recursive call không có base case |
+| Connection refused | Dependency chưa chạy | Kiểm tra config URL / khởi động service |
+| 401 Unauthorized | Token hết hạn, sai config | Verify token, kiểm tra auth config |
+| 403 Forbidden | Sai role | Kiểm tra auth annotation |
+| DB constraint violation | Trùng key, null trong NOT NULL | Kiểm tra data và constraint |
+| Serialization error | Circular reference | Kiểm tra config DTO/mapper |
+| Test assertion mismatch | Sai mock hoặc sai expected | Đọc lại setup mock |
 
 #### context-engineering (AI/LLM pipelines)
 
-| Error | Likely Cause | Fix Direction |
+| Error | Nguyên nhân khả nghi | Hướng fix |
 |-------|-------------|---------------|
-| `APIError` / `RateLimitError` | LLM quota exceeded or service down | Check API key, rate limits; add exponential backoff |
-| `TokenLimitError` / `context_length_exceeded` | Input prompt too long | Truncate/chunk input; review prompt template size |
-| `AuthenticationError` | API key invalid or expired | Check env var; rotate key |
-| Response validation / schema mismatch | LLM output doesn't match expected format | Add output parser; retry with stricter prompt |
-| `JSONDecodeError` on LLM output | Model returned non-JSON text | Add JSON extraction post-processing or stricter system prompt |
-| Hanging / slow test | Real LLM called in test instead of mock | Verify `patch('...')` applied; add timeout guard |
-| Flaky results across runs | Non-deterministic LLM response | Use fixed mock in tests; check temperature = 0 for determinism |
+| `APIError` / `RateLimitError` | Vượt quota LLM hoặc service down | Kiểm tra API key, rate limit; thêm exponential backoff |
+| `TokenLimitError` / `context_length_exceeded` | Prompt input quá dài | Truncate/chunk input; review kích thước prompt template |
+| `AuthenticationError` | API key không hợp lệ hoặc hết hạn | Kiểm tra env var; rotate key |
+| Response validation / schema mismatch | Output LLM không khớp format kỳ vọng | Thêm output parser; retry với prompt chặt hơn |
+| `JSONDecodeError` trên output LLM | Model trả về text non-JSON | Thêm post-processing trích JSON hoặc system prompt chặt hơn |
+| Test treo / chậm | LLM thật bị gọi trong test thay vì mock | Verify `patch('...')` được áp; thêm timeout guard |
+| Kết quả flaky giữa các lần chạy | Response LLM non-deterministic | Dùng mock cố định trong test; check temperature = 0 cho determinism |
 
-### If `platform_type = web-frontend`
+### Nếu `platform_type = web-frontend`
 
-| Error | Likely Cause | Fix Direction |
+| Error | Nguyên nhân khả nghi | Hướng fix |
 |-------|-------------|---------------|
-| `Cannot read properties of undefined` | Data not loaded yet | Add loading guard / optional chaining `?.` |
-| `useEffect` infinite loop | Dependency array wrong | Review deps, use stable refs / `useCallback` |
-| `Cannot update state on unmounted component` | Async resolves after unmount | Cancel in cleanup / use AbortController |
-| CORS error | API not configured | Check backend CORS config or dev proxy setup |
-| 401 Unauthorized | Token expired or missing | Refresh token / check Authorization header |
-| White screen / no output | Unhandled render error | Check browser console, add ErrorBoundary |
-| Type error (Zod / TypeScript) | API response shape mismatch | Compare actual response vs type definition |
-| `act(...)` warning in test | Async state update | Wrap in `act(async () => {...})` |
-| Module not found | Import path wrong | Check relative path / tsconfig alias |
-
-### If `platform_type = mobile`
+| `Cannot read properties of undefined` | Data chưa load | Thêm loading guard / optional chaining `?.` |
+| `useEffect` infinite loop | Dependency array sai | Review deps, dùng stable ref / `useCallback` |
+| `Cannot update state on unmounted component` | Async resolve sau unmount | Cancel trong cleanup / dùng AbortController |
+| CORS error | API chưa cấu hình | Kiểm tra CORS config backend hoặc dev proxy |
+| 401 Unauthorized | Token hết hạn hoặc thiếu | Refresh token / kiểm tra header Authorization |
+| White screen / no output | Render error chưa xử lý | Kiểm tra console browser, thêm ErrorBoundary |
+| Type error (Zod / TypeScript) | Shape response API mismatch | So response thực tế vs type definition |
+| `act(...)` warning trong test | Async state update | Bọc trong `act(async () => {...})` |
+| Module not found | Sai import path | Kiểm tra relative path / tsconfig alias |
+
+### Nếu `platform_type = mobile`
 
 #### Flutter
-| Error | Likely Cause | Fix Direction |
+| Error | Nguyên nhân khả nghi | Hướng fix |
 |-------|-------------|---------------|
-| `Null check operator on null value` | Nullable not guarded | Add `?` or null check before `!` |
-| `pumpAndSettle timed out` | Async not completing in test | Use `pump(Duration(...))` |
-| `setState called after dispose` | Async continues after widget removed | Cancel in `dispose()` |
-| `RenderFlex overflow` | Widget too wide for screen | Wrap with `Flexible`, `Expanded`, or `SingleChildScrollView` |
-| BLoC state not updating | Event not dispatched | Verify `bloc.add(Event())` is called |
-| `MissingPluginException` | Native plugin not linked | Run `flutter clean && flutter pub get` |
+| `Null check operator on null value` | Nullable chưa guard | Thêm `?` hoặc null check trước `!` |
+| `pumpAndSettle timed out` | Async chưa hoàn thành trong test | Dùng `pump(Duration(...))` |
+| `setState called after dispose` | Async tiếp tục sau khi widget bị bỏ | Cancel trong `dispose()` |
+| `RenderFlex overflow` | Widget quá rộng so với màn | Bọc `Flexible`, `Expanded`, hoặc `SingleChildScrollView` |
+| BLoC state không update | Event chưa dispatch | Verify `bloc.add(Event())` được gọi |
+| `MissingPluginException` | Native plugin chưa link | Chạy `flutter clean && flutter pub get` |
 
 #### React Native
-| Error | Likely Cause | Fix Direction |
+| Error | Nguyên nhân khả nghi | Hướng fix |
 |-------|-------------|---------------|
-| `undefined is not an object` | Null prop access | Add null check / optional chaining |
+| `undefined is not an object` | Truy cập prop null | Thêm null check / optional chaining |
 | Metro bundler error | Cache stale | `npx react-native start --reset-cache` |
-| `VirtualizedLists nested` | FlatList inside ScrollView | Use `nestedScrollEnabled` or restructure |
-| Navigation `undefined` | `useNavigation` outside navigator | Wrap component inside correct navigator |
-| `act(...)` warning | Async state update in test | Wrap in `act(async () => {...})` |
+| `VirtualizedLists nested` | FlatList trong ScrollView | Dùng `nestedScrollEnabled` hoặc tái cấu trúc |
+| Navigation `undefined` | `useNavigation` ngoài navigator | Bọc component trong đúng navigator |
+| `act(...)` warning | Async state update trong test | Bọc trong `act(async () => {...})` |
 
 #### iOS / Android
-| Error | Likely Cause | Fix Direction |
+| Error | Nguyên nhân khả nghi | Hướng fix |
 |-------|-------------|---------------|
-| `SIGABRT` / `EXC_BAD_ACCESS` (iOS) | Nil dereference | Add optional binding `if let` / `guard let` |
-| `IllegalStateException` (Android) | Lifecycle violation | Check if fragment/activity still attached |
-| `NetworkOnMainThreadException` | Network call on UI thread | Move to coroutine / background thread |
-| Build fails after pod install | Pod cache stale | `pod deintegrate && pod install` |
-| `Hilt injection failed` | Missing `@AndroidEntryPoint` | Add annotation to Activity/Fragment |
+| `SIGABRT` / `EXC_BAD_ACCESS` (iOS) | Nil dereference | Thêm optional binding `if let` / `guard let` |
+| `IllegalStateException` (Android) | Vi phạm lifecycle | Kiểm tra fragment/activity còn attached không |
+| `NetworkOnMainThreadException` | Network call trên UI thread | Chuyển sang coroutine / background thread |
+| Build fail sau pod install | Pod cache stale | `pod deintegrate && pod install` |
+| `Hilt injection failed` | Thiếu `@AndroidEntryPoint` | Thêm annotation vào Activity/Fragment |
 
 ## Test Failure Analysis
 
@@ -209,7 +209,7 @@ Expected: {value}
 Actual  : {value}
   at {test}.{method}(line {N})
 ```
-1. What is the gap? 2. Is mock setup correct? 3. Is assertion logically correct?
+1. Gap là gì? 2. Mock setup đúng chưa? 3. Assertion có đúng logic không?
 
 ---
 
@@ -224,34 +224,34 @@ Actual  : {value}
 {description}
 
 ## Root Cause
-{technical explanation}
+{giải thích kỹ thuật}
 
 ## Location
 File: {path} | Line: {N} | Layer: {Controller/Service/Repository/Test}
 
 ## Suggested Fix
-{specific code change}
+{thay đổi code cụ thể}
 
 ## Related Rule
-See CLAUDE.md §{section}
+Xem CLAUDE.md §{section}
 
 ## Next Step
-- To fully fix → /fix-bug {TICKET_ID}
-- Just needed analysis → done
+- Để fix hoàn toàn → /fix-bug {TICKET_ID}
+- Chỉ cần phân tích → xong
 ```
 
 ---
 
-## Offer to Record a Lesson (optional)
+## Đề xuất ghi Lesson (tuỳ chọn)
 
-If the root cause is a **mistake the AI made when generating code and could repeat**
-(not an environment/config issue or external cause), ask:
+Nếu root cause là một **lỗi AI gây ra khi sinh code và có thể lặp lại**
+(không phải vấn đề env/config hay nguyên nhân bên ngoài), hỏi:
 
 ```
-This looks like a repeatable AI mistake. Record it as a project lesson? (Y/N)
+Cái này trông như một lỗi AI lặp lại. Ghi nó thành project lesson? (Y/N)
 ```
 
-If `Y` → run the capture procedure below with `source=/debug`, 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=/debug`, 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}}