@educa-corp/sdd-framework 0.6.0 → 0.7.0

package/commands/debug.tmpl

@@ -1,260 +0,0 @@
-# /debug — Phân tích Debug nhanh
-
-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
-
-*Checkpoint: **không chặn** — read-only. Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
-
-{{include:steps/gate.md}}
-
-*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 — Phân loại loại debug
-
-Sau khi nạp context, hiện prompt này và chờ user chọn:
-
-```
-DEBUG SESSION
-──────────────────────────────────────────────────────────────
-  Tình huống của bạn?
-
-  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
-──────────────────────────────────────────────────────────────
-Nhập 1 / 2 / 3 / 4:
-```
-
-Chờ user chọn, rồi theo path tương ứng bên dưới.
-
----
-
-### Path 1 — Đã có error output
-
-Hỏi:
-```
-Dán stack trace / error log của bạn bên dưới:
-```
-
-Chờ input, rồi sang [Stack Trace Analysis](#stack-trace-analysis).
-
----
-
-### Path 2 — Cần reproduce trước
-
-Hiện lệnh run từ `conventions.service_run` trong `project-context.yaml`:
-
-```
-Khởi động service trước:
-
-  {conventions.service_run}
-
-(Nếu dùng Docker: `docker compose up -d`, rồi verify với `docker compose ps`)
-
-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
-
-Đang chờ error output của bạn...
-```
-
-Chờ user dán lỗi, rồi sang [Stack Trace Analysis](#stack-trace-analysis).
-
-Nếu `conventions.service_run` chưa set → hiện:
-```
-⚠️  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.
-```
-Rồi nhờ user khởi động service thủ công và dán lỗi khi sẵn sàng.
-
----
-
-### Path 3 — Test đang fail
-
-Hiện lệnh test từ `conventions.test_command` trong `project-context.yaml`:
-
-```
-Chạy test của bạn trước:
-
-  {conventions.test_command}
-
-Khi chạy xong, dán full output test fail vào đây.
-
-Đang chờ...
-```
-
-Chờ user dán output fail, rồi sang [Test Failure Analysis](#test-failure-analysis).
-
-Nếu `conventions.test_command` chưa set → hiện:
-```
-⚠️  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.
-```
-Rồi nhờ user chạy test thủ công và dán output khi sẵn sàng.
-
----
-
-### Path 4 — Câu hỏi code
-
-Hỏi:
-```
-Mô tả câu hỏi của bạn hoặc dán code snippet bạn đang hỏi:
-```
-
-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
-
-Đọc từ **dưới lên** — `Caused by:` là root cause thật:
-```
-Caused by: {RealException}  ← bắt đầu ở đây
-  at {class}.{method}({file}:{line})
-```
-
-## Common Error Patterns
-
-Dùng `active_module` từ context để chọn bảng liên quan.
-
-### Nếu `platform_type = backend`
-
-#### java-spring / golang / dotnet / php-laravel
-
-| Error | Nguyên nhân khả nghi | Hướng fix |
-|-------|-------------|---------------|
-| 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 | Nguyên nhân khả nghi | Hướng fix |
-|-------|-------------|---------------|
-| `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 |
-
-### Nếu `platform_type = web-frontend`
-
-| Error | Nguyên nhân khả nghi | Hướng fix |
-|-------|-------------|---------------|
-| `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 | Nguyên nhân khả nghi | Hướng fix |
-|-------|-------------|---------------|
-| `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 | Nguyên nhân khả nghi | Hướng fix |
-|-------|-------------|---------------|
-| `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 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 | Nguyên nhân khả nghi | Hướng fix |
-|-------|-------------|---------------|
-| `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
-
-```
-Expected: {value}
-Actual  : {value}
-  at {test}.{method}(line {N})
-```
-1. Gap là gì? 2. Mock setup đúng chưa? 3. Assertion có đúng logic không?
-
----
-
-## Output
-
-{{include:steps/report-footer.md}}
-
-```
-/debug Analysis
-
-## Error
-{description}
-
-## Root Cause
-{giải thích kỹ thuật}
-
-## Location
-File: {path} | Line: {N} | Layer: {Controller/Service/Repository/Test}
-
-## Suggested Fix
-{thay đổi code cụ thể}
-
-## Related Rule
-Xem CLAUDE.md §{section}
-
-## Next Step
-- Để fix hoàn toàn → /fix-bug {TICKET_ID}
-- Chỉ cần phân tích → xong
-```
-
----
-
-## Đề xuất ghi Lesson (tuỳ chọn)
-
-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:
-
-```
-Cái này trông như một lỗi AI lặp lại. Ghi nó thành project lesson? (Y/N)
-```
-
-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}}