| name | bugfix-skill |
| description | Use when: reproducing and fixing runtime, logic, routing, or state bugs with a root-cause-first workflow. |
Skill: Bugfix và Khôi phục lỗi cho Beacon
Mục tiêu
Sửa lỗi đúng nguyên nhân gốc, giảm nguy cơ phát sinh regressions ở auth, router, network và state management.
Khi dùng
- Bug runtime/crash
- Logic sai kết quả
- Điều hướng sai hoặc guard sai
- UI state bị kẹt loading/error
Đầu vào tối thiểu
- Cách tái hiện bug
- Kết quả hiện tại và mong đợi
- Phạm vi ảnh hưởng (màn/feature)
Quy trình 5 bước
1) Reproduce
- Tái hiện bug ổn định ít nhất 1 lần.
2) Localize
- Khoanh vùng lớp gây lỗi: presentation/domain/data/core.
- Xác định source-of-truth tương ứng.
3) Reduce
- Tối giản input/context để tìm điều kiện kích hoạt chính.
4) Fix
- Sửa root cause với thay đổi tối thiểu.
- Không mở rộng refactor nếu không cần.
5) Guard
- Thêm kiểm chứng để bug không quay lại (test hoặc checklist verify).
Heuristics theo vùng lỗi
- Routing:
app_routes.dart, app_router.dart, AuthGuard.
- Message:
app_message_notifier.dart, GlobalMessageOverlay, MessageToast.
- API:
api_endpoints.dart, datasource impl, ApiHandler, repository mapping failure.
- Auth state:
AuthNotifier, AuthState, token lifecycle local datasource.
Stop-the-line criteria
Phải dừng merge nếu bug liên quan:
- Mất dữ liệu người dùng
- Lộ token/thông tin nhạy cảm
- Không đăng nhập/đăng xuất được
- Crash ngay luồng chính
Verify bắt buộc
- Re-test đúng steps gây lỗi ban đầu
- Chạy
flutter analyze
- Chạy thêm 1-2 flow liền kề để check regression
Done khi
- Bug không còn tái hiện theo steps cũ
- Không phát sinh lỗi mới ở luồng lân cận
- Có mô tả ngắn root cause và hướng fix
