alp-code 0.9.0

package/skills/alp-debug/references/log-and-ci-analysis.md

@@ -0,0 +1,96 @@
+# Phân tích log và CI/CD
+
+## GitHub Actions
+
+```bash
+gh run list --limit 10                    # các lần chạy gần đây
+gh run list --workflow=ci.yml --limit 5   # theo workflow
+gh run view <run-id>                      # chi tiết, trạng thái từng bước
+gh run view <run-id> --log-failed         # CHỈ log của job hỏng — bắt đầu ở đây
+gh run view <run-id> --log > /tmp/ci.txt  # tải hết
+```
+
+Luôn bắt đầu bằng `--log-failed`. Tải log đầy đủ trước rồi đọc là cách nhanh nhất để nhấn
+chìm context bằng hàng nghìn dòng xanh.
+
+`gh run rerun <run-id> --failed` chạy lại job hỏng — nhưng **đó là thao tác tốn tài nguyên
+và tác động ra ngoài**: báo lại, đừng tự chạy để "xem thử có phải flaky không".
+
+### Mẫu hỏng thường gặp
+
+| Mẫu | Nguyên nhân hay gặp | Kiểm gì |
+|---|---|---|
+| máy chạy được, CI hỏng | khác môi trường | phiên bản Node/Python, OS, biến môi trường |
+| lúc hỏng lúc không | race, test flaky | chạy 3 lần, xem thời điểm, trạng thái dùng chung |
+| timeout | giới hạn tài nguyên, vòng lặp vô hạn | mức dùng tài nguyên, có timeout chưa |
+| lỗi quyền | token/secret sai cấu hình | `GITHUB_TOKEN`, tên secret |
+| cài phụ thuộc hỏng | registry, xung đột phiên bản | lockfile, trạng thái registry |
+| build được, test hỏng | môi trường test | config test, database, fixture |
+
+Dòng đầu đáng chú ý nhất: **"máy chạy được, CI hỏng" gần như luôn là khác biệt môi
+trường**, không phải bug trong code. So biến môi trường trước khi đọc code.
+
+### Đọc bước hỏng
+
+1. `gh run view <id>` — xác định **bước nào** hỏng.
+2. `gh run view <id> --log-failed` — lấy log tập trung.
+3. Tìm mẫu lỗi: `Error:`, `FAIL`, `exit code`, stack trace.
+4. Xem annotation: `gh api repos/{owner}/{repo}/check-runs/{id}/annotations`.
+
+## Log server
+
+### Cách thu
+
+1. **Xác định chỗ chứa log** — log ứng dụng, log hệ thống, log web server.
+2. **Lọc theo khung thời gian** của sự cố.
+3. **Đối chiếu theo request ID** — lần một request qua nhiều dịch vụ.
+4. **Tìm mẫu** — lỗi lặp, tỷ lệ lỗi đổi, payload bất thường.
+
+### Truy vấn database
+
+```bash
+# truy vấn chậm
+psql -c "SELECT query, calls, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
+
+# trạng thái kết nối
+psql -c "SELECT count(*), state FROM pg_stat_activity GROUP BY state;"
+```
+
+Chỉ chạy truy vấn **đọc**. `UPDATE`, `DELETE`, `ALTER` trên database thật là thao tác khó
+đảo ngược, phải xin principal duyệt.
+
+### Đối chiếu chéo nguồn
+
+1. **Căn mốc thời gian** giữa mọi nguồn — chú ý múi giờ, đây là chỗ hay sai nhất.
+2. **Dựng timeline** — lỗi đầu tiên → lan ra → người dùng thấy.
+3. **Tìm chỗ kích hoạt** — cái gì đổi ngay trước lỗi đầu tiên?
+4. **Vẽ bán kính ảnh hưởng** — dịch vụ/endpoint nào bị.
+
+## Đọc mẫu lỗi ứng dụng
+
+| Hình dạng | Nghĩa thường là |
+|---|---|
+| vọt lên đột ngột | deploy, đổi config, phụ thuộc ngoài chết |
+| tăng dần | rò tài nguyên, dữ liệu phình, xuống cấp |
+| hỏng theo chu kỳ | cron, tác vụ định kỳ, tranh chấp tài nguyên |
+| chỉ một endpoint | bug code, vấn đề dữ liệu, một phụ thuộc cụ thể |
+| mọi endpoint | hạ tầng, database, mạng |
+
+Hình dạng theo thời gian nói nhiều hơn nội dung một dòng lỗi. Vẽ nó trước khi đọc chi tiết.
+
+### Trường log ưu tiên
+
+mốc thời gian · mức · thông báo lỗi · stack trace · request ID · endpoint · mã phản hồi ·
+thời lượng.
+
+## Giữ bằng chứng
+
+Trích **đúng phần cần** cho báo cáo, không dán cả file log:
+
+- Thông báo lỗi và stack trace nguyên văn.
+- Mốc thời gian và request ID.
+- So sánh trước/sau — trạng thái bình thường và trạng thái lỗi.
+- Số lượng và tần suất, không phải tính từ.
+
+"Rất nhiều lỗi timeout" là vô dụng. "412 lỗi timeout trong 5 phút, so với 0 ở khung giờ
+trước" thì dùng được.

package/skills/alp-debug/references/performance-diagnostics.md

@@ -0,0 +1,112 @@
+# Chẩn đoán hiệu năng
+
+## Khi nào dùng
+
+Thời gian phản hồi tăng rõ rệt · ứng dụng chậm · truy vấn lâu · CPU/bộ nhớ/đĩa cao · cạn
+tài nguyên hoặc OOM.
+
+## Luật vào nghề
+
+**Đo trước, tối ưu sau.** Tối ưu mà không có số đo trước là đoán — và thường tối ưu đúng
+chỗ không phải nút thắt.
+
+Bốn câu phải trả lời trước khi động vào bất cứ thứ gì:
+
+- Kỳ vọng bao nhiêu, thực tế bao nhiêu? (số cụ thể, không phải "chậm")
+- Chậm từ khi nào? Trùng với thay đổi nào?
+- Endpoint / thao tác nào bị?
+- Luôn luôn hay lúc có lúc không?
+
+## Khoanh tầng nút thắt
+
+```
+Request → Mạng → Web server → Ứng dụng → Database → Filesystem
+                                 ↓
+                          API / dịch vụ ngoài
+```
+
+Đo thời gian ở **từng tầng** để biết độ trễ nằm ở đâu. Loại trừ, đừng đoán.
+
+| Tầng | Kiểm | Công cụ |
+|---|---|---|
+| Mạng | độ trễ, DNS, TLS | `curl -w`, log mạng |
+| Web server | hàng đợi request, số kết nối | metric server, access log |
+| Ứng dụng | CPU, bộ nhớ | profiler, `process.memoryUsage()` |
+| Database | thời gian truy vấn, kết nối | `EXPLAIN ANALYZE`, `pg_stat_statements` |
+| Filesystem | I/O wait, dung lượng | `iostat`, `df -h` |
+| API ngoài | thời gian phản hồi, timeout | log request kèm thời lượng |
+
+## Database — PostgreSQL
+
+Toàn bộ truy vấn dưới đây là **chỉ đọc**. Không chạy `UPDATE`/`ALTER`/`DELETE` trên
+database thật — đó là thao tác khó đảo ngược, phải xin principal duyệt.
+
+```sql
+-- truy vấn chậm (cần extension pg_stat_statements)
+SELECT query, calls, mean_exec_time, total_exec_time
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC LIMIT 20;
+
+-- truy vấn đang chạy ngay lúc này
+SELECT pid, now() - query_start AS duration, query, state
+FROM pg_stat_activity
+WHERE state != 'idle'
+ORDER BY duration DESC;
+
+-- kích thước bảng
+SELECT relname, pg_size_pretty(pg_total_relation_size(relid))
+FROM pg_catalog.pg_statio_user_tables
+ORDER BY pg_total_relation_size(relid) DESC LIMIT 20;
+
+-- thiếu index: quét tuần tự nhiều trên bảng lớn
+SELECT relname, seq_scan, seq_tup_read, idx_scan
+FROM pg_stat_user_tables
+WHERE seq_scan > 100 AND seq_tup_read > 10000
+ORDER BY seq_tup_read DESC;
+
+-- trạng thái pool kết nối
+SELECT count(*), state FROM pg_stat_activity GROUP BY state;
+```
+
+Phân tích một truy vấn cụ thể:
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) <truy vấn>;
+```
+
+**Tìm:** quét tuần tự trên bảng lớn · nested loop với số dòng cao · sort không có index ·
+số lần chạm buffer bất thường.
+
+## Ứng dụng — nút thắt thường gặp
+
+| Vấn đề | Triệu chứng | Hướng sửa |
+|---|---|---|
+| N+1 truy vấn | rất nhiều truy vấn nhỏ mỗi request | nạp sớm, gộp truy vấn |
+| Rò bộ nhớ | bộ nhớ tăng dần theo thời gian | profile heap, kiểm event listener |
+| I/O chặn | thời gian phản hồi cao, CPU thấp | bất đồng bộ, pool kết nối |
+| Nghẽn CPU | CPU cao, tỷ lệ thuận với tải | tối ưu thuật toán, cache |
+| Cạn kết nối | timeout lúc có lúc không | chỉnh kích thước pool, dùng lại kết nối |
+| Payload lớn | truyền chậm, tốn bộ nhớ | phân trang, nén, streaming |
+
+Cặp **"thời gian phản hồi cao + CPU thấp"** là dấu hiệu rõ nhất: hệ đang **chờ**, không
+phải đang **tính**. Đừng đi tối ưu thuật toán khi CPU đang rảnh.
+
+## Thứ tự tối ưu
+
+1. **Thắng nhanh** — thêm index còn thiếu, sửa N+1, bật cache.
+2. **Cấu hình** — kích thước pool, timeout, buffer, số worker.
+3. **Code** — tối ưu thuật toán, đổi cấu trúc dữ liệu.
+4. **Kiến trúc** — tầng cache, read replica, xử lý bất đồng bộ, CDN.
+
+Đi từ trên xuống. Bước 4 đắt và khó đảo ngược; bước 1 thường giải quyết phần lớn vấn đề.
+
+**Mỗi lần một thay đổi, đo lại sau mỗi lần.** Đổi ba thứ cùng lúc rồi thấy nhanh hơn thì
+không biết thứ nào có tác dụng — và hai thứ kia có thể đang làm chậm đi.
+
+## Đưa vào báo cáo
+
+- **Số đo trước và sau**, có con số. Không có số thì không phải chẩn đoán hiệu năng.
+- **Nút thắt nằm ở tầng nào**, kèm bằng chứng.
+- **Nguyên nhân gốc** — vì sao tầng đó chậm.
+- **Đề xuất sửa** kèm tác động mong đợi.
+- **Cách kiểm chứng** rằng bản sửa có hiệu quả.

package/skills/alp-debug/references/reporting-standards.md

@@ -0,0 +1,120 @@
+# Chuẩn báo cáo điều tra
+
+Hy sinh ngữ pháp cho cô đọng. Sự kiện và bằng chứng, không kể chuyện.
+
+## Khi nào viết ra file
+
+Điều tra ngắn → trả lời thẳng trong phiên, không tạo file.
+
+Viết file khi: điều tra nhiều bước còn dùng lại được, sự cố cần hậu kiểm, hoặc được yêu cầu.
+
+**Đường dẫn:** `plans/reports/{loại}-{YYMMDD}-{HHMM}-{slug}.md`
+
+Tự tính ngày giờ — alp-code không có hook nào inject đường dẫn.
+
+**Lưu ý ACL:** loadout có thể không cấp `Write` — khi đó bạn không tự tạo được file báo
+cáo. Đưa nội dung cho bên giao việc để họ ghi. Đừng tìm đường vòng qua `Bash`
+(HOUSE-RULES §1.9).
+
+## Cấu trúc
+
+### 1. Tóm tắt (3–5 dòng)
+
+- **Vấn đề:** một dòng
+- **Ảnh hưởng:** ai/hệ nào, mức nghiêm trọng
+- **Nguyên nhân gốc:** một dòng — hoặc **"chưa xác định được"**
+- **Trạng thái:** đã xong · đã giảm thiểu · đang điều tra
+- **Đề xuất sửa:** ở đâu, vì sao ở đó
+
+Chưa ra nguyên nhân gốc thì **ghi thẳng là chưa ra**. Thay bằng nguyên nhân gần nhất là
+cách để người đọc đi sửa nhầm chỗ.
+
+### 2. Phân tích
+
+**Mốc thời gian** — chỉ khi sự cố diễn ra theo thời gian:
+
+```
+HH:MM — sự kiện
+HH:MM — sự kiện
+```
+
+**Chuỗi bằng chứng** — phần quan trọng nhất:
+
+```
+1. <quan sát>  — `path:line` hoặc output lệnh
+2. <suy ra>    — vì sao bước 1 dẫn tới đây
+```
+
+Người đọc phải đi lại được chuỗi này và tới cùng kết luận. Bước nào không đi lại được thì bước
+đó là giả thuyết, phải ghi là giả thuyết.
+
+**Tách ba loại, đừng trộn:**
+
+| Loại | Cách viết |
+|---|---|
+| Đã xác nhận | "chạy X, output cho thấy Y" |
+| Giả thuyết | "có thể do X — chưa tái hiện được" |
+| Tương quan | "X và Y cùng xuất hiện — chưa chứng minh nhân quả" |
+
+Nhầm tương quan thành nhân quả là lỗi hay gặp nhất trong báo cáo điều tra.
+
+### 3. Đã loại trừ
+
+Giả thuyết nào đã thử và **bị bác**, bằng bằng chứng gì.
+
+Mục này hay bị bỏ và nó đắt: không có nó, người đọc sẽ đi lại đúng con đường bạn vừa đi.
+
+### 4. Khuyến nghị
+
+| Mức | Nghĩa |
+|---|---|
+| Ngay | sửa để hết vấn đề |
+| Tiếp theo | cải thiện sau khi hết cháy |
+| Lâu dài | giám sát, cảnh báo, phòng ngừa tái diễn |
+
+Mỗi khuyến nghị: **làm gì · vì sao · tác động mong đợi · công sức (thấp/vừa/cao)**.
+
+Khuyến nghị nào là thao tác khó đảo ngược (migration, xoá dữ liệu, đổi cấu hình
+production) thì đánh dấu rõ **cần principal duyệt**.
+
+### 5. Câu hỏi còn mở
+
+Luôn có mục này. Phần chưa rõ, giả định cần kiểm chứng, và thứ bạn không tự lấy được.
+
+## Mẫu
+
+```markdown
+# <Vấn đề> — Báo cáo điều tra
+
+## Tóm tắt
+- **Vấn đề:**
+- **Ảnh hưởng:**
+- **Nguyên nhân gốc:**
+- **Trạng thái:**
+- **Đề xuất sửa:**
+
+## Chuỗi bằng chứng
+1.
+2.
+
+## Đã loại trừ
+-
+
+## Khuyến nghị
+### Ngay
+- [ ]
+### Tiếp theo
+- [ ]
+### Lâu dài
+- [ ]
+
+## Câu hỏi còn mở
+-
+```
+
+## Luật viết
+
+- **Có bằng chứng:** mọi khẳng định kèm log, số đo, hoặc bước tái hiện.
+- **Trung thực:** nói rõ cái gì không biết. "Nhiều khả năng là" khác "đã xác nhận là".
+- **Cụ thể:** khuyến nghị chỉ được `path:line`, không nói chung chung.
+- **Quét được bằng mắt:** tiêu đề, bảng, gạch đầu dòng.

package/skills/alp-debug/references/root-cause-tracing.md

@@ -0,0 +1,134 @@
+# Lần ngược nguyên nhân gốc
+
+Lần ngược call stack tới chỗ **phát sinh**, không dừng ở chỗ lỗi nổ ra.
+
+## Nguyên lý
+
+Bug thường nổ **sâu** trong call stack. Bản năng là sửa ngay chỗ báo lỗi — đó là chữa
+triệu chứng. Giá trị sai đã đi qua nhiều tầng trước khi tới đó, và mỗi tầng đều là một cơ
+hội bị bỏ lỡ để chặn nó.
+
+## Khi nào dùng
+
+- Lỗi xảy ra sâu trong luồng thực thi, không phải ở cửa vào.
+- Stack trace dài.
+- Chưa rõ dữ liệu sai sinh ra từ đâu.
+- Cần biết test nào hoặc đường code nào kích hoạt.
+
+## Quy trình
+
+### 1. Quan sát triệu chứng
+
+```
+Error: git init failed in /Users/oaidq/project/packages/core
+```
+
+### 2. Tìm nguyên nhân trực tiếp
+
+Dòng code nào gây ra nó?
+
+```js
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Hỏi: ai gọi dòng này?
+
+```
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  ← Session.initializeWorkspace()
+  ← Session.create()
+  ← test tại Project.create()
+```
+
+### 4. Lần tiếp lên trên — giá trị nào được truyền vào?
+
+- `projectDir = ''` — chuỗi rỗng.
+- Chuỗi rỗng làm `cwd` thì rơi về `process.cwd()`.
+- Đó là thư mục source.
+
+### 5. Tìm chỗ phát sinh
+
+Chuỗi rỗng từ đâu ra?
+
+```js
+const context = setupCoreTest();       // trả { tempDir: '' }
+Project.create('name', context.tempDir); // đọc TRƯỚC khi beforeEach chạy
+```
+
+**Nguyên nhân gốc:** biến ở tầng ngoài được khởi tạo khi giá trị chưa sẵn sàng.
+**Không phải** `git init`, cũng không phải `WorktreeManager`.
+
+## Chèn stack trace khi lần tay không nổi
+
+```js
+async function gitInit(directory) {
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    stack: new Error().stack,
+  });
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+Dùng `console.error()`, **không** dùng logger — logger trong test hay bị nuốt.
+
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+Đọc stack trace tìm: tên file test · số dòng kích hoạt · mẫu lặp (cùng một test? cùng một
+tham số?).
+
+**Lưu ý ACL:** loadout có thể không cấp `Edit` — khi đó bạn không tự chèn được đoạn debug
+này. Mô tả chính xác chèn gì, vào file nào, dòng nào, rồi để người có quyền chèn và chạy.
+Đừng tìm đường vòng qua `Bash` (HOUSE-RULES §1.9).
+
+## Tìm test nào gây nhiễm
+
+Có thứ xuất hiện trong lúc chạy test mà không biết test nào tạo ra:
+
+```bash
+.claude/skills/alp-debug/scripts/find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Chạy từng test một, dừng ở test đầu tiên gây nhiễm. Đường dẫn tính từ CWD của phiên
+(`active workspace`), qua symlink skill.
+
+## Luật
+
+**Không bao giờ chỉ sửa ở chỗ lỗi nổ ra.**
+
+Tìm được nguyên nhân trực tiếp rồi thì hỏi tiếp:
+
+- Lần lên được một tầng nữa không? → lần tiếp.
+- Đây đúng là chỗ phát sinh? → đề xuất sửa ở đây.
+- Rồi đề xuất thêm chốt chặn ở từng tầng — `defense-in-depth.md`.
+
+## Ví dụ thật, đủ chuỗi
+
+**Triệu chứng:** `.git` được tạo trong `packages/core/` (thư mục source).
+
+**Chuỗi lần ngược:**
+
+1. `git init` chạy trong `process.cwd()` ← tham số `cwd` rỗng
+2. `WorktreeManager` nhận `projectDir` rỗng
+3. `Session.create()` truyền chuỗi rỗng
+4. test đọc `context.tempDir` trước khi `beforeEach` chạy
+5. `setupCoreTest()` ban đầu trả `{ tempDir: '' }`
+
+**Nguyên nhân gốc:** khởi tạo biến ở tầng ngoài, đọc giá trị chưa sẵn sàng.
+
+**Sửa:** biến `tempDir` thành getter, ném lỗi nếu bị đọc trước `beforeEach`.
+
+**Chốt chặn thêm:**
+
+| Tầng | Chốt |
+|---|---|
+| 1 | `Project.create()` kiểm thư mục |
+| 2 | `WorkspaceManager` từ chối chuỗi rỗng |
+| 3 | guard môi trường: từ chối `git init` ngoài thư mục tạm |
+| 4 | log stack trace trước khi `git init` |
+
+Chuỗi này là mẫu cho phần **Chuỗi bằng chứng** trong báo cáo — người đọc phải đi lại được
+từng bước và tới cùng kết luận.

package/skills/alp-debug/references/systematic-debugging.md

@@ -0,0 +1,93 @@
+# Gỡ lỗi có hệ thống
+
+Bốn pha. Pha này xong mới sang pha kia.
+
+## Luật sắt
+
+```
+KHÔNG ĐỀ XUẤT SỬA KHI CHƯA TRUY XONG NGUYÊN NHÂN GỐC
+```
+
+Chưa xong Pha 1 thì không được đề xuất cách sửa.
+
+Nếu loadout không cấp `Edit` thì luật này còn dễ giữ hơn: bạn **không sửa được gì**. Sản
+phẩm của bạn là nguyên nhân gốc kèm chuỗi bằng chứng; người khác mới là người sửa.
+
+## Pha 1 — Truy nguyên nhân gốc
+
+1. **Đọc kỹ thông báo lỗi.** Đọc hết stack trace, đừng lướt qua warning. Dòng bạn bỏ qua
+   thường là dòng nói thật.
+2. **Tái hiện ổn định.** Kích hoạt lại được không? Chính xác các bước nào? Không tái hiện
+   được → thu thập thêm dữ liệu, **chưa** đưa giả thuyết.
+3. **Xem gì vừa đổi.** `git diff`, commit gần đây, phụ thuộc mới, config đổi.
+4. **Thu bằng chứng ở ranh giới giữa các thành phần.** Với mỗi ranh giới: dữ liệu vào là
+   gì, ra là gì, biến môi trường có truyền qua không. Chạy **một lượt** để biết nó vỡ ở
+   *đâu*, rồi mới phân tích *vì sao*.
+5. **Lần theo dòng dữ liệu.** Giá trị sai sinh ra từ đâu? Lần ngược call stack tới nguồn —
+   xem `root-cause-tracing.md`.
+
+Chưa xong 5 bước này thì mọi giả thuyết đều là đoán.
+
+## Pha 2 — Phân tích mẫu
+
+1. **Tìm ví dụ đang chạy đúng.** Code tương tự trong cùng repo mà không hỏng.
+2. **Đọc bản tham chiếu ĐẦY ĐỦ** trước khi so. Đọc lướt rồi so là cách bỏ sót đúng khác
+   biệt quan trọng.
+3. **Liệt kê mọi khác biệt**, dù nhỏ. Không được tự nhủ "chỗ đó không thể ảnh hưởng".
+4. **Hiểu phụ thuộc** — cần thành phần nào, config nào, biến môi trường nào.
+
+## Pha 3 — Giả thuyết và kiểm chứng
+
+1. **Một giả thuyết, cụ thể:** "tôi cho rằng X là nguyên nhân gốc vì Y". Không phải "chắc
+   do phần auth".
+2. **Thử tối thiểu** — thay đổi nhỏ nhất đủ để kiểm giả thuyết. **Một biến một lần.**
+3. **Kiểm chứng trước khi đi tiếp.** Đúng → Pha 4. Sai → giả thuyết **mới**, không phải
+   chồng thêm bản sửa.
+4. **Không biết thì nói không biết.** "Tôi chưa hiểu vì sao X" là câu hợp lệ. Giả vờ hiểu
+   là cách để người đọc đi sửa nhầm chỗ.
+
+## Pha 4 — Kết luận và bàn giao
+
+1. **Tái hiện được, càng nhỏ càng tốt.** Tự động hoá được thì tốt. Đây là thứ chứng minh
+   nguyên nhân gốc đúng.
+2. **Một đề xuất sửa duy nhất**, nhắm nguyên nhân gốc. Không kèm "tiện tay cải thiện luôn".
+3. **Chỉ rõ vì sao sửa ở đó**, chứ không phải ở chỗ triệu chứng nổ ra.
+4. **Đề xuất không đứng vững:**
+   - DỪNG. Đếm: đã thử mấy giả thuyết?
+   - Dưới 3 → về Pha 1 với thông tin mới.
+   - **Từ 3 trở lên → dừng và chất vấn kiến trúc.**
+5. **Ba lần thất bại nghĩa là gì.** Mẫu điển hình: mỗi lần sửa lại lộ ra một chỗ dùng chung
+   trạng thái hoặc coupling khác. Đó không còn là bug, đó là kiến trúc sai. Dừng, báo lại,
+   và cân nhắc `alp-predict` hoặc `problem-solving` thay vì thử tiếp.
+
+## Cờ đỏ — dừng lại, quay về Pha 1
+
+- "sửa tạm đã, điều tra sau"
+- "cứ thử đổi X xem sao"
+- "đổi vài chỗ rồi chạy test"
+- "bỏ qua test, kiểm tay cũng được"
+- "chắc là do X, sửa chỗ đó"
+- "tôi chưa hiểu hết nhưng chắc cách này được"
+- "thử thêm một lần nữa thôi" — khi đã thử 2+ lần
+
+## Tín hiệu cho thấy bạn đang làm sai
+
+| Nghe câu này | Nghĩa là |
+|---|---|
+| "thế nó có xảy ra không?" | bạn đang giả định mà chưa kiểm |
+| "chạy cái đó có cho thấy gì không?" | lẽ ra phải thu bằng chứng trước |
+| "đừng đoán nữa" | đang đề xuất sửa khi chưa hiểu |
+| "nghĩ kỹ lại từ gốc" | chất vấn nền tảng, không phải triệu chứng |
+
+Gặp mấy câu này → về Pha 1.
+
+## Chặn biện minh
+
+| Lý do | Thực tế |
+|---|---|
+| "lỗi đơn giản, không cần quy trình" | lỗi đơn giản cũng có nguyên nhân gốc |
+| "gấp lắm, không kịp làm quy trình" | có hệ thống **nhanh hơn** đoán-và-thử |
+| "thử cái này trước rồi điều tra sau" | lần thử đầu đặt luôn lối mòn |
+| "thử thêm lần nữa" (sau 2 lần hỏng) | 3 lần hỏng = vấn đề kiến trúc |
+
+Cái giá thật: có hệ thống mất 15–30 phút; đoán bừa mất 2–3 giờ và hay đẻ bug mới.

package/skills/alp-debug/references/verification.md

@@ -0,0 +1,86 @@
+# Kiểm chứng trước khi kết luận
+
+Đây là việc chẩn đoán, không phải việc sửa. Nên thứ bạn phải kiểm chứng không phải "đã làm
+xong chưa" mà là **"kết luận này có đứng vững không"**.
+
+Nói sai nguyên nhân gốc còn tệ hơn nói không biết: người ta sẽ đi sửa nhầm chỗ, mất thời
+gian gấp đôi, và lần sau không tin bạn nữa.
+
+## Luật sắt
+
+```
+KHÔNG KẾT LUẬN KHI CHƯA CÓ BẰNG CHỨNG MỚI, LẤY TRONG PHIÊN NÀY
+```
+
+## Hàm cổng
+
+```
+TRƯỚC khi nói bất cứ kết luận nào:
+
+1. XÁC ĐỊNH: lệnh hoặc quan sát nào chứng minh được điều này?
+2. CHẠY:     chạy đủ, mới, không cắt
+3. ĐỌC:      đọc hết output, xem exit code, đếm số fail
+4. ĐỐI CHIẾU: output có xác nhận không?
+   - KHÔNG → nói trạng thái thật, kèm bằng chứng
+   - CÓ    → nói kết luận, KÈM bằng chứng
+5. RỒI MỚI: phát biểu
+
+Bỏ bước nào = đoán, không phải kết luận
+```
+
+## Ba mức tin cậy — phải nói rõ mức nào
+
+| Mức | Điều kiện | Viết thế nào |
+|---|---|---|
+| **Đã xác nhận** | tái hiện được, có output | "chạy X, output cho thấy Y" |
+| **Giả thuyết** | hợp lý nhưng chưa tái hiện | "có thể do X — chưa tái hiện được" |
+| **Tương quan** | hai thứ cùng xuất hiện | "X và Y cùng xuất hiện — chưa chứng minh nhân quả" |
+
+Trộn ba mức này vào cùng một giọng khẳng định là lỗi hay gặp nhất trong báo cáo điều tra.
+
+## Bảng đối chiếu
+
+| Kết luận | Bằng chứng bắt buộc | KHÔNG đủ |
+|---|---|---|
+| đây là nguyên nhân gốc | tái hiện được, và gỡ nguyên nhân thì triệu chứng biến mất | code đọc thấy có vẻ sai |
+| lỗi nằm ở thành phần X | log ở ranh giới cho thấy dữ liệu vào đúng, ra sai | X là chỗ stack trace nổ |
+| test fail do môi trường | chạy lại ở môi trường sạch: pass | "chắc do máy CI" |
+| chậm vì truy vấn N+1 | có số đo: số truy vấn, thời gian | đọc code thấy vòng lặp có query |
+| đã loại trừ giả thuyết Y | thử Y, kết quả bác bỏ | thấy Y không hợp lý |
+
+## Cờ đỏ — dừng lại
+
+- Dùng "chắc là", "nhiều khả năng", "có vẻ" trong phần **Nguyên nhân gốc**.
+- Kết luận dựa trên đọc code mà chưa chạy gì.
+- Nhận báo cáo của agent khác làm bằng chứng — nó chạy phiên riêng, bạn không thấy nó đã
+  chạy gì.
+- Dừng ở nguyên nhân **gần nhất** vì nó đủ hợp lý.
+- Mệt và muốn xong cho rồi.
+
+## Chặn biện minh
+
+| Lý do | Thực tế |
+|---|---|
+| "đọc code là thấy ngay mà" | đọc code cho giả thuyết, không cho kết luận |
+| "tôi khá chắc" | chắc ≠ bằng chứng |
+| "không tái hiện được nhưng chắc đúng" | thì ghi là giả thuyết, đừng ghi là nguyên nhân gốc |
+| "đang gấp" | kết luận sai làm mất nhiều thời gian hơn |
+| "bên kia đã kiểm rồi" | kiểm độc lập, hoặc ghi rõ là dựa vào báo cáo của họ |
+
+## Bài kiểm quyết định
+
+Một nguyên nhân gốc chỉ được gọi là **đã xác nhận** khi trả lời được cả hai:
+
+1. **Tái hiện được triệu chứng** theo đúng cơ chế đã mô tả?
+2. **Gỡ nguyên nhân đi thì triệu chứng biến mất?** — hoặc chứng minh được bằng suy luận từ
+   bằng chứng đã có.
+
+Không trả lời được câu 2 thì đó vẫn là giả thuyết mạnh, không phải nguyên nhân gốc. Nói
+đúng như vậy trong báo cáo.
+
+## Chốt
+
+Chạy. Đọc output. **Rồi mới** kết luận.
+
+Chưa ra thì nói chưa ra, kèm danh sách đã loại trừ. Đó là câu trả lời hợp lệ và hữu ích —
+Một lượt chẩn đoán được mở ra vì độ tin cậy, không vì tốc độ.