dev-debug

name	dev-debug
description	Systematic debugging — tìm root cause trước khi fix. Reproduce → Localize → Reduce → Fix → Guard. Trigger khi: user nói "debug lỗi", "tìm nguyên nhân bug", "tại sao bị lỗi", "fix bug", "investigate error", "lỗi không biết tại sao", hoặc gõ /dev-debug.

Skill: /dev-debug

Role: Developer
Mục đích: Systematic debugging — tìm root cause trước khi fix. Tránh "fix ngẫu nhiên cho đến khi hết lỗi".

---

Nguyên tắc cốt lõi

Không bao giờ touch code trước khi có minimal reproduction.
Fix sai root cause = tạo thêm bugs.

Quy trình 5 bước

Bước 1 — Reproduce

## Tôi sẽ giúp debug vấn đề này.

Trước tiên:

| # | Câu hỏi | Lựa chọn |
|---|---------|---------|
| 1 | Mô tả lỗi: gì xảy ra vs gì mong đợi? | _(điền vào)_ |
| 2 | Steps to reproduce | _(điền vào — dù rough cũng được)_ |
| 3 | Lỗi này mới xuất hiện hay luôn có? | A: Mới xuất hiện — sau thay đổi: ___ / B: Luôn có / C: Không chắc / D: Khác: ___ |
| 4 | Error message / stack trace | _(paste vào đây nếu có)_ |

Ask First Gate: Nếu lỗi xảy ra trên production với user thật → báo ngay cho team trước khi debug. Xem thêm assets/ask-first-gates.md.

Bước 2 — Localize

Spawn subagent để đọc code liên quan (read-only):

"Tìm code xử lý [behavior mô tả]. Trả về file:line và flow từ entry point đến điểm có thể fail. Không sửa gì."

Trình bày:

## Tôi xác định vùng code có thể là nguồn lỗi:

1. [file:line] — [lý do suspect]
2. [file:line] — [lý do suspect]

Hypothesis:
- H1: [Giả thuyết 1 về nguyên nhân]
- H2: [Giả thuyết 2]

Tôi sẽ kiểm tra H1 trước vì [lý do].
Bạn có thêm hypothesis nào dựa trên context bạn biết không?

Bước 3 — Reduce

Tạo minimal reproduction — code nhỏ nhất có thể trigger lỗi.

## Minimal reproduction:

[Code snippet hoặc steps tối thiểu]

Lỗi có reproduce với code này không?
(Nếu không → vấn đề nằm ở interaction với phần khác, không phải đây)

Không tiếp tục nếu chưa có minimal reproduction.

Bước 4 — Fix

Chỉ sau khi xác nhận root cause:

## Root cause xác định: [Mô tả rõ]

Đề xuất fix:
- Fix A: [Targeted fix] — sửa đúng chỗ, ít side effect
- Fix B: [Broader fix] — sửa cả pattern, nhiều file hơn

Đề xuất Fix A trước (nhỏ hơn, dễ review hơn).

| | Lựa chọn |
|---|---------|
| A | Đồng ý — Fix A |
| B | Muốn Fix B (broader) |
| C | Khác: ___ |

Ask First Gate: Nếu fix liên quan đến bất kỳ thay đổi nhạy cảm nào (assets/ask-first-gates.md) → cần senior review trước khi apply.

Bước 5 — Guard

Sau khi fix:

## Fix đã apply.

Tôi cũng sẽ thêm test để prevent regression:
[Mô tả test case]

| | Lựa chọn |
|---|---------|
| A | Không, đủ rồi |
| B | Có — edge case: ___ |
| C | Khác: ___ |

---

Red Flags (dừng lại nếu thấy)

• Đang thử fix nhiều thứ cùng lúc mà không hiểu tại sao
• Lỗi "biến mất" nhưng không biết tại sao
• Fix xong nhưng không thể reproduce được trường hợp fail ban đầu
• Stack trace trỏ vào library code — thường là cách dùng sai, không phải bug trong lib