alp-code 0.9.0

package/skills/gkg/references/language-support.md

@@ -0,0 +1,54 @@
+# Hỗ trợ ngôn ngữ của gkg
+
+## Bảng
+
+| Ngôn ngữ | Định nghĩa | Import | Tham chiếu trong file | Tham chiếu chéo file |
+|---|---|---|---|---|
+| Ruby | ✅ | ✅ | ✅ | ✅ |
+| Java | ✅ | ✅ | ✅ | ✅ |
+| Kotlin | ✅ | ✅ | ✅ | ✅ |
+| Python | ✅ | ✅ | ✅ | **chưa xong** |
+| TypeScript | ✅ | ✅ | ✅ | **chưa xong** |
+| JavaScript | ✅ | ✅ | ✅ | **chưa xong** |
+
+## Bốn năng lực nghĩa là gì
+
+| Năng lực | Nội dung |
+|---|---|
+| **Định nghĩa** | class, hàm, method, hằng, interface — rút từ AST |
+| **Import** | theo dõi import module/package để dựng đồ thị phụ thuộc |
+| **Tham chiếu trong file** | chỗ dùng symbol nằm cùng file |
+| **Tham chiếu chéo file** | chỗ dùng symbol định nghĩa ở file khác — **đây là cái quyết định phân tích ảnh hưởng** |
+
+Cột cuối là cột duy nhất thật sự quan trọng khi truy xuất code. Ba cột đầu `rg` cũng làm
+gần được.
+
+## Ruby / Java / Kotlin — dùng tự tin
+
+Phân tích ngữ nghĩa đầy đủ: tìm định nghĩa chéo file · tìm mọi chỗ gọi · đồ thị phụ thuộc
+đầy đủ · phân tích ảnh hưởng trước refactor.
+
+## Python / TS / JS — dùng có điều kiện
+
+Chạy được: rút định nghĩa, theo dõi import, tham chiếu trong cùng file.
+
+**Không đầy đủ:**
+
+- `get_references` chéo file **có thể bỏ sót** chỗ dùng.
+- `get_definition` có thể không giải được symbol từ bên ngoài.
+
+Đây là điểm quan trọng nhất của cả file này. Với TS/JS/Python:
+
+1. **Luôn đối chiếu thêm bằng `rg`.** `gkg` cho quan hệ, `rg` cho độ phủ — cần cả hai.
+2. **Ghi rõ trong báo cáo là kết quả chưa chắc đầy đủ.**
+3. Việc quan trọng (ai đó sắp refactor) thì kiểm tay thêm những chỗ then chốt.
+
+Trả lời "có 3 chỗ gọi" khi thật ra có 11 là kiểu sai đắt nhất một lượt truy xuất có thể
+gây ra — người ta sẽ refactor dựa trên con số đó.
+
+## Đây là beta công khai
+
+Không phải công cụ đã chín. Hỗ trợ tham chiếu chéo file cho Python/TS/JS đang được làm —
+xem https://gitlab.com/gitlab-org/rust/knowledge-graph để biết trạng thái mới.
+
+Đến khi nào cột cuối của TS/JS chuyển thành ✅ thì luật đối chiếu bằng `rg` vẫn còn hiệu lực.

package/skills/problem-solving/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: problem-solving
+description: Sáu kỹ thuật gỡ bế tắc có hệ thống — dùng khi độ phức tạp phình ra, khi giải pháp thông thường không đủ, khi cùng một vấn đề lặp ở nhiều nơi, khi bị ép vào "chỉ có một cách", hoặc khi không rõ có chịu nổi quy mô thật.
+---
+
+# problem-solving — gỡ bế tắc có hệ thống
+
+Dùng khi *đã* thử và *đã* bế tắc — nên việc của skill này không phải nghĩ chăm hơn, mà là
+**đổi kiểu nghĩ**.
+
+Mỗi kỹ thuật nhắm một dạng bế tắc khác nhau. Chẩn đoán sai dạng thì kỹ thuật vô dụng, nên
+bước 1 là bước quan trọng nhất.
+
+## Chẩn đoán trước
+
+| Triệu chứng | Kỹ thuật | Đọc |
+|---|---|---|
+| cùng một thứ triển khai 5 kiểu, special case cứ mọc thêm | **Thác đơn giản hoá** | `references/simplification-cascades.md` |
+| cách thông thường không đủ, cần đột phá | **Vùng va chạm** | `references/collision-zone-thinking.md` |
+| cùng một vấn đề ở nhiều chỗ khác nhau, phát minh lại bánh xe | **Nhận mẫu meta** | `references/meta-pattern-recognition.md` |
+| giải pháp thấy gượng, "buộc phải làm thế này" | **Bài tập đảo ngược** | `references/inversion-exercise.md` |
+| chạy thật có chịu nổi không, edge case chưa rõ | **Trò chơi quy mô** | `references/scale-game.md` |
+| không rõ dùng cái nào | **Khi bế tắc** | `references/when-stuck.md` |
+
+## Sáu kỹ thuật
+
+### 1. Thác đơn giản hoá
+Tìm **một** nhận định xoá được nhiều thành phần cùng lúc: "nếu điều này đúng thì không cần
+X, Y, Z nữa."
+
+Cốt lõi: mọi thứ đang có đều là trường hợp riêng của một mẫu chung chưa được đặt tên.
+Cờ đỏ: "chỉ cần thêm một case nữa thôi" — lặp mãi không hết.
+
+### 2. Vùng va chạm
+Ép hai khái niệm không liên quan vào nhau để lộ tính chất mới: "nếu coi X như Y thì sao?"
+
+Cốt lõi: ý tưởng đột phá đến từ trộn ẩn dụ có chủ đích, không từ nghĩ chăm hơn trong cùng
+một khung.
+Cờ đỏ: "tôi thử hết cách trong mảng này rồi."
+
+### 3. Nhận mẫu meta
+Tìm mẫu xuất hiện ở 3+ lĩnh vực khác nhau để rút ra nguyên lý dùng chung được.
+
+Cốt lõi: mẫu về **cách các mẫu hình thành** cho ra trừu tượng tái dùng được.
+Cờ đỏ: "vấn đề này là đặc thù, không giống ai" — hầu như luôn sai.
+
+### 4. Bài tập đảo ngược
+Lật giả định lõi để lộ ràng buộc ngầm: "nếu ngược lại thì sao?"
+
+Cốt lõi: đảo ngược *hợp lệ* cho thấy "luật" thật ra chỉ đúng trong một ngữ cảnh.
+Cờ đỏ: "chỉ có một cách làm thôi."
+
+### 5. Trò chơi quy mô
+Thử ở cực trị: lớn gấp 1000, nhỏ đi 1000, tức thì, kéo dài một năm.
+
+Cốt lõi: thứ chạy tốt ở quy mô này hỏng ở quy mô khác — và cực trị lộ ra đâu là bản chất,
+đâu là ngẫu nhiên.
+Cờ đỏ: "chắc scale được thôi" mà chưa thử.
+
+### 6. Khi bế tắc
+Cây quyết định để chọn năm cái trên. Dùng khi chẩn đoán không ra dạng bế tắc.
+
+## Cách áp dụng
+
+1. **Chẩn đoán dạng bế tắc** từ mô tả của việc được giao — bảng trên.
+2. **Đọc file reference** của kỹ thuật đó. SKILL.md này chỉ là bảng điều phối; quy trình
+   thật nằm trong reference.
+3. **Áp dụng theo đúng quy trình**, không rút gọn. Rút gọn là quay lại kiểu nghĩ cũ.
+4. **Ghi lại cái gì hiệu quả, cái gì không.** Bài học về chính cách bạn làm việc →
+   `memory/private/<vai>/journal/YYYY-MM.md`. Fact về project → báo lại; bên giao việc quyết
+   định ghi vào `memory/` chung hay không.
+
+## Kết hợp
+
+- **Đơn giản hoá + Nhận mẫu meta** — tìm mẫu trước, rồi đơn giản hoá mọi thể hiện của nó.
+- **Va chạm + Đảo ngược** — ép ẩn dụ, rồi lật giả định của chính ẩn dụ đó.
+- **Quy mô + Đơn giản hoá** — cực trị cho thấy nên bỏ cái gì.
+- **Nhận mẫu meta + Quy mô** — nguyên lý chung đem thử ở cực trị.
+
+## Ranh giới
+
+Đây là việc **đọc và suy luận**, không phải việc sửa. Kết quả là một khuyến nghị, không
+phải một thay đổi trong code — kể cả khi loadout có cấp `Edit`.
+
+Cần dữ liệu bạn không tự lấy được → **nói rõ cần gì** rồi báo lại. Đừng đoán bù vào chỗ
+thiếu dữ liệu.

package/skills/problem-solving/references/attribution.md

@@ -0,0 +1,48 @@
+# Nguồn gốc
+
+Các kỹ thuật trong skill này bắt nguồn từ mẫu agent của dự án Microsoft Amplifier, qua hai
+lần thích nghi.
+
+## Nguồn gốc
+
+- **Dự án:** Amplifier — https://github.com/microsoft/amplifier
+- **Commit:** `2adb63f858e7d760e188197c8e8d4c1ef721e2a6` (2025-10-10)
+- **Giấy phép:** MIT
+
+## Chuỗi thích nghi
+
+```
+Amplifier (agent JSON)  →  alp-plugin (skill tra cứu)  →  alp-code (skill của repo)
+```
+
+### Lần 1 — Amplifier → alp-plugin
+
+Từ agent `insight-synthesizer`: `simplification-cascades` · `collision-zone-thinking` ·
+`meta-pattern-recognition` · `inversion-exercise` · `scale-game`.
+
+Mẫu điều phối: `when-stuck` — khớp triệu chứng bế tắc với kỹ thuật.
+
+Đổi: agent sống lâu, xuất JSON có cấu trúc → tài liệu tra cứu quét được bằng mắt, dùng
+được ngay, không cần công cụ riêng.
+
+### Lần 2 — alp-plugin → alp-code (2026-08)
+
+Đổi:
+
+- Dịch sang tiếng Việt, khớp `compiled policy invariants` và `HOUSE-RULES.md`.
+- Viết cho **một lượt gỡ bế tắc**, không gắn với tên vai nào — vai nào được cấp skill này
+  là việc của `compiled AgentDefinition`, không phải của nội dung skill.
+- Thêm ranh giới theo **loadout**, không theo tên vai: không cấp `Edit` thì sản phẩm là
+  khuyến nghị, không phải thay đổi trong code.
+- Thêm ví dụ lấy từ chính alp-code ở chỗ ví dụ gốc quá xa ngữ cảnh.
+- Tách rõ "bế tắc tư duy" (dùng skill này) khỏi "thiếu bằng chứng" (dùng `alp-debug`).
+
+**Giữ nguyên:** năm kỹ thuật lõi, mẫu nhận diện, quy trình áp dụng, và luật 3 lĩnh vực.
+
+## Nhận định nền
+
+Năng lực của một agent thực ra là **mẫu tư duy không phụ thuộc lĩnh vực**. Gói nó thành
+"agent Amplifier", "skill alp-plugin" hay "một lượt gỡ bế tắc" thì kỹ thuật bên dưới vẫn
+là một.
+
+Đó cũng chính là `meta-pattern-recognition` áp dụng lên chính nó.

package/skills/problem-solving/references/collision-zone-thinking.md

@@ -0,0 +1,71 @@
+# Vùng va chạm
+
+Ép hai khái niệm không liên quan vào nhau để lộ tính chất mới: **"nếu coi X như Y thì sao?"**
+
+## Nguyên lý
+
+Đột phá đến từ **trộn ẩn dụ có chủ đích**, không từ nghĩ chăm hơn trong cùng một khung.
+Nghĩ chăm hơn trong khung cũ chỉ cho ra cải tiến từng bước.
+
+## Khi nào dùng
+
+| Triệu chứng | Việc phải làm |
+|---|---|
+| kẹt trong lối nghĩ thông thường | ép va chạm với một lĩnh vực xa |
+| giải pháp nào cũng chỉ nhích thêm chút | cần đột phá, không phải tối ưu |
+| "thử hết cách trong mảng này rồi" | nhập khái niệm từ nơi khác |
+
+## Va chạm mẫu
+
+| Coi cái này | Như cái này | Lộ ra |
+|---|---|---|
+| tổ chức code | DNA / di truyền | mutation testing, thuật toán tiến hoá |
+| kiến trúc dịch vụ | gạch Lego | microservice ghép được, cắm-là-chạy |
+| quản lý dữ liệu | dòng nước | streaming, data lake, hệ theo luồng |
+| xử lý request | thư bưu điện | hàng đợi, xử lý bất đồng bộ |
+| xử lý lỗi | cầu dao điện | cô lập sự cố, xuống cấp có kiểm soát |
+
+## Quy trình
+
+1. **Chọn hai khái niệm không liên quan**, từ hai lĩnh vực khác nhau.
+2. **Ép ghép** — "nếu coi A như B thì sao?"
+3. **Khai thác tính chất mới** — xuất hiện năng lực nào chưa từng nghĩ tới?
+4. **Thử biên** — ẩn dụ gãy ở đâu?
+5. **Rút nhận định.**
+
+**Bước 4 là bước không được bỏ.** Ẩn dụ nào cũng gãy ở đâu đó; biết nó gãy chỗ nào mới là
+phần dùng được. Đem một ẩn dụ đi quá biên của nó là cách sinh ra kiến trúc sai một cách
+thanh lịch.
+
+## Ví dụ chi tiết
+
+**Vấn đề:** hệ phân tán, lỗi lan dây chuyền.
+
+**Va chạm:** "nếu coi service như mạch điện?"
+
+**Tính chất mới:**
+- cầu dao (ngắt khi quá tải)
+- cầu chì (bảo vệ một lần)
+- nối đất (cô lập lỗi)
+- cân tải (phân bổ dòng)
+- ổn áp (giới hạn tần suất)
+
+**Chỗ ẩn dụ đúng:** chặn lỗi lan, cô lập sự cố.
+
+**Chỗ ẩn dụ gãy:** mạch điện không có retry, không tự lành.
+
+**Nhận định rút ra:** mẫu cô lập sự cố mượn được từ kỹ thuật điện; mẫu tự phục hồi thì
+phải lấy từ chỗ khác — sinh học chẳng hạn.
+
+## Lĩnh vực nguồn tốt
+
+**Vật lý** (lực, nhiệt động, tương đối) · **Sinh học** (tiến hoá, hệ sinh thái, miễn dịch)
+· **Kinh tế** (thị trường, động lực, lý thuyết trò chơi) · **Tâm lý** (nhận thức, hành vi)
+· **Kiến trúc** (kết cấu, luồng di chuyển, tổ chức không gian).
+
+## Nhớ
+
+- Ghép càng lạ càng hay ra nhận định tốt. Ghép an toàn thì chỉ ra thứ đã biết.
+- Ghi lại cả va chạm **thất bại** — chỗ ẩn dụ gãy cũng là thông tin.
+- Câu hỏi mở khoá: **"người giỏi nhất ở lĩnh vực kia sẽ làm gì với bài toán này?"**
+- Đem về dưới dạng khuyến nghị kèm biên của ẩn dụ, đừng đem về một ẩn dụ trần.

package/skills/problem-solving/references/inversion-exercise.md

@@ -0,0 +1,88 @@
+# Bài tập đảo ngược
+
+Lật giả định lõi để lộ ràng buộc ngầm: **"nếu ngược lại thì sao?"**
+
+## Nguyên lý
+
+**Đảo ngược làm lộ giả định chưa ai nói ra.** Đôi khi cái ngược lại mới là câu trả lời —
+nhưng kể cả khi không, việc lật cũng cho thấy vì sao cái đang có là đúng.
+
+## Khi nào dùng
+
+| Triệu chứng | Việc phải làm |
+|---|---|
+| "chỉ có một cách thôi" | lật giả định đó |
+| giải pháp thấy gượng | lật ràng buộc |
+| không nói được vì sao nó bắt buộc | chất vấn chữ "phải" |
+| "xưa nay vẫn làm thế" | thử làm ngược |
+
+## Đảo ngược mẫu
+
+| Giả định thường | Lật lại | Lộ ra |
+|---|---|---|
+| cache để giảm độ trễ | thêm độ trễ để cache được | mẫu debounce |
+| kéo dữ liệu khi cần | đẩy dữ liệu trước khi cần | prefetch, nạp sớm |
+| xử lý lỗi khi lỗi xảy ra | làm cho lỗi không thể xảy ra | hệ kiểu, contract |
+| thêm tính năng người dùng muốn | bỏ tính năng người dùng không cần | đơn giản > bổ sung |
+| tối ưu cho ca phổ biến | tối ưu cho ca tệ nhất | mẫu chịu lỗi |
+
+## Quy trình
+
+1. **Liệt kê giả định lõi** — cái gì đang được coi là "phải" đúng?
+2. **Lật từng cái** — "nếu ngược lại thì sao?"
+3. **Truy hệ quả** — làm khác đi thế nào?
+4. **Tìm đảo ngược hợp lệ** — cái nào thật sự chạy được ở đâu đó?
+5. **Ghi nhận định.**
+
+## Ví dụ
+
+**Vấn đề:** người dùng kêu app chậm.
+
+**Cách thường:** làm mọi thứ nhanh hơn — cache, tối ưu truy vấn, CDN, giảm bundle.
+
+**Lật lại:** cố tình làm chậm ở vài chỗ.
+
+- **Debounce ô tìm kiếm** — thêm độ trễ → kết quả tốt hơn (đợi gõ xong).
+- **Giới hạn tần suất** — thêm ma sát → chặn lạm dụng, người khác được phục vụ tốt hơn.
+- **Lazy load** — hoãn tải → thời gian tải đầu ngắn lại.
+- **Render dần** — hiện chậm hơn nhưng hiện sớm → *cảm giác* nhanh hơn.
+
+**Nhận định:** chậm có chiến lược cải thiện trải nghiệm. Cái người dùng cảm nhận không phải
+tổng thời gian, mà là thời gian phải chờ trước khi thấy gì đó.
+
+## Đảo ngược hợp lệ và không hợp lệ
+
+**Hợp lệ:**
+- Thường: "lưu dữ liệu vào database."
+- Lật: "tính lại khi cần thay vì lưu."
+- Hợp lệ khi: tính rẻ hơn lưu, dữ liệu đổi liên tục.
+
+**Không hợp lệ:**
+- Thường: "kiểm dữ liệu người dùng nhập."
+- Lật: "tin mọi dữ liệu nhập vào."
+- Không hợp lệ vì: đó là lỗ bảo mật, không phụ thuộc ngữ cảnh nào cả.
+
+**Cách thử:** đảo ngược này có chạy được trong **bất kỳ** ngữ cảnh nào không? Có → nó hợp
+lệ ở đâu đó, đáng khám phá. Không → bỏ, đừng cố.
+
+## Cặp hay lật
+
+Sớm ↔ lười · đẩy ↔ kéo · lưu ↔ tính · tối ưu ↔ đơn giản hoá · thêm ↔ bớt.
+
+## Với alp-code
+
+Repo này có sẵn vài giả định đáng lật khi bế tắc:
+
+- "ACL phải do harness enforce" ↔ "nếu hook không chạy thì sao?" — chính câu hỏi này sinh
+  ra thiết kế fail đóng hiện tại.
+- "mỗi vai một phiên riêng" ↔ "nếu gộp thì sao?" — lật để thấy vì sao tách là đúng.
+
+Lật một nguyên tắc trong `compiled policy invariants` là bài tập tư duy hợp lệ. **Đề xuất đổi nó thì phải
+qua principal** — chỉ principal sửa CHARTER (compiled policy invariants).
+
+## Nhớ
+
+- Không phải đảo ngược nào cũng chạy. Thử biên.
+- Đảo ngược hợp lệ cho thấy "luật" thật ra chỉ đúng trong một ngữ cảnh.
+- Ghi lại cả lần lật thất bại — nó chứng minh vì sao cách hiện tại đúng, và đó là thứ đáng
+  ghi vào plan.

package/skills/problem-solving/references/meta-pattern-recognition.md

@@ -0,0 +1,80 @@
+# Nhận mẫu meta
+
+Tìm mẫu xuất hiện ở **3+ lĩnh vực** để rút ra nguyên lý dùng chung được.
+
+## Nguyên lý
+
+**Tìm mẫu trong cách các mẫu hình thành.** Cùng một hình dạng xuất hiện ở 3 lĩnh vực không
+liên quan thì nhiều khả năng nó là nguyên lý phổ quát, đáng rút ra.
+
+## Khi nào dùng
+
+| Triệu chứng | Việc phải làm |
+|---|---|
+| cùng vấn đề ở nhiều chỗ khác nhau | rút dạng trừu tượng |
+| cảm giác đã gặp bài này rồi | tìm mẫu phổ quát |
+| phát minh lại bánh xe ở nhiều mảng | nhận diện mẫu meta |
+| "hình như mình làm cái này rồi?" | rồi — tìm lại và dùng lại |
+
+## Mẫu tham chiếu
+
+| Mẫu xuất hiện ở | Dạng trừu tượng | Còn ở đâu nữa |
+|---|---|---|
+| cache CPU / DB / HTTP / DNS | đưa dữ liệu hay dùng lại gần chỗ dùng | cache prompt LLM, CDN |
+| phân lớp (mạng / lưu trữ / tính toán) | tách mối quan tâm thành các tầng trừu tượng | kiến trúc, cơ cấu tổ chức |
+| hàng đợi (message / task / request) | tách người sản xuất khỏi người tiêu thụ bằng bộ đệm | hệ sự kiện, bất đồng bộ |
+| pool (kết nối / thread / object) | dùng lại tài nguyên đắt | quản lý bộ nhớ |
+
+## Quy trình
+
+1. **Thấy lặp lại** — cùng một hình dạng ở 3+ chỗ.
+2. **Rút dạng trừu tượng** — mô tả nó mà **không nhắc tới lĩnh vực nào**.
+3. **Nhận điểm biến thiên** — mỗi lĩnh vực thích nghi khác nhau ở chỗ nào?
+4. **Kiểm khả dụng** — còn chỗ nào dùng được nữa?
+5. **Ghi lại mẫu** cho lần sau.
+
+Bước 2 là bài kiểm tra thật: **mô tả được mà không nhắc lĩnh vực nào không?** Không mô tả
+được nghĩa là bạn đang thấy ba thứ giống nhau bề ngoài, không phải một mẫu.
+
+## Ví dụ
+
+**Mẫu:** giới hạn tần suất xuất hiện ở —
+
+- throttle API (request mỗi phút)
+- định hình lưu lượng mạng (gói tin mỗi giây)
+- cầu dao (số lỗi trong một cửa sổ)
+- kiểm soát nạp vào (số kết nối đồng thời)
+
+**Dạng trừu tượng:** chặn mức tiêu thụ tài nguyên để tránh cạn kiệt.
+
+**Điểm biến thiên:** tài nguyên gì · giới hạn theo cửa sổ thời gian hay đồng thời hay tích
+luỹ · vượt thì làm gì (từ chối, xếp hàng, xuống cấp).
+
+**Ứng dụng mới:** ngân sách token cho LLM — cùng mẫu, tài nguyên là token, giới hạn là
+kích thước cửa sổ context, vượt thì cắt bớt hoặc từ chối.
+
+Ngân sách 5 lượt tìm của `research` và giới hạn "boot set ≤ 7 nguồn" của CHARTER §2.6
+cũng là cùng mẫu này.
+
+## Luật 3 lĩnh vực
+
+| Số lần thấy | Nghĩa |
+|---|---|
+| 1 | trùng hợp |
+| 2 | có thể là mẫu |
+| 3+ | nhiều khả năng phổ quát |
+
+Rút mẫu từ 2 lần thấy là trừu tượng hoá sớm — và trừu tượng sai đắt hơn trùng lặp.
+
+## Cờ đỏ — đang bỏ lỡ mẫu meta
+
+- "vấn đề này đặc thù, không giống ai" — hầu như luôn sai.
+- Nhiều người đang giải những bài "khác nhau" theo cách giống hệt nhau.
+- Phát minh lại bánh xe ở các mảng khác nhau.
+
+## Nhớ
+
+- Dạng trừu tượng cho thấy **ứng dụng mới** — đó mới là giá trị, không phải việc đặt tên.
+- Điểm biến thiên cho biết mẫu thích nghi ở đâu, và ở đâu thì gãy.
+- Ghi lại để lần sau khỏi tìm lại — với alp-code, fact loại này thuộc `memory/shared/`,
+  và việc ghi thuộc về bên có quyền ghi.

package/skills/problem-solving/references/scale-game.md

@@ -0,0 +1,82 @@
+# Trò chơi quy mô
+
+Thử ở cực trị — lớn gấp 1000, nhỏ đi 1000, tức thì, kéo dài một năm — để lộ ra bản chất bị
+che ở quy mô bình thường.
+
+## Nguyên lý
+
+**Cực trị làm lộ bản chất.** Thứ chạy tốt ở quy mô này hỏng ở quy mô khác, và chỗ nó hỏng
+cho biết cái gì là thiết yếu, cái gì chỉ là ngẫu nhiên.
+
+## Khi nào dùng
+
+| Triệu chứng | Việc phải làm |
+|---|---|
+| "chắc scale được" mà chưa thử | thử ở cực trị |
+| không rõ chạy thật sẽ thế nào | nhân lên 1000 lần |
+| edge case chưa rõ | thử cả tối thiểu lẫn tối đa |
+| cần thẩm định kiến trúc | thử cực trị trước khi chốt |
+
+## Các chiều
+
+| Chiều | Thử ở cực trị | Lộ ra |
+|---|---|---|
+| **Khối lượng** | 1 phần tử ↔ 1 tỷ | giới hạn độ phức tạp thuật toán |
+| **Tốc độ** | tức thì ↔ một năm | nhu cầu bất đồng bộ, nhu cầu cache |
+| **Người dùng** | 1 ↔ 1 tỷ | vấn đề đồng thời, giới hạn tài nguyên |
+| **Thời lượng** | mili giây ↔ nhiều năm | rò bộ nhớ, trạng thái phình |
+| **Tỷ lệ lỗi** | không bao giờ lỗi ↔ luôn lỗi | xử lý lỗi có đủ không |
+
+## Quy trình
+
+1. **Chọn chiều** — cái gì có thể biến thiên cực đoan?
+2. **Thử cực tiểu** — nhỏ/nhanh/ít đi 1000 lần thì sao?
+3. **Thử cực đại** — lớn/chậm/nhiều lên 1000 lần thì sao?
+4. **Ghi cái gì vỡ** — giới hạn nằm ở đâu?
+5. **Ghi cái gì sống** — phần nào vững về bản chất?
+6. **Thiết kế cho thực tế** — dùng nhận định để thẩm định kiến trúc.
+
+## Ví dụ
+
+**Xử lý lỗi.** Quy mô thường: "có lỗi thì xử lý" — ổn. Ở 1 tỷ: lượng lỗi làm ngập hệ log,
+sập hệ. → Phải làm cho lỗi **không thể xảy ra** (hệ kiểu), hoặc **coi lỗi là bình thường**
+(thiết kế chịu lỗi). Thiết kế xử lý lỗi theo *khối lượng*, không chỉ theo *sự kiện*.
+
+**API đồng bộ.** Quy mô thường: gọi trực tiếp, dưới 100ms — ổn. Quy mô toàn cầu: độ trễ
+mạng 200–500ms làm đồng bộ không dùng được. → Bất đồng bộ trở thành điều kiện sống, không
+phải tối ưu.
+
+**Trạng thái trong bộ nhớ.** Chạy vài giờ/vài ngày: ổn. Chạy nhiều năm: bộ nhớ phình vô
+hạn, sập. → Cần lưu ra ngoài hoặc dọn định kỳ.
+
+## Chiều nhỏ cũng quan trọng
+
+Thử **nhỏ lại** hay bị bỏ qua, mà nó lộ ra over-engineering:
+
+- Nếu chỉ có 1 người dùng thì độ phức tạp này còn hợp lý không?
+- Nếu chỉ có 10 phần tử thì tối ưu kia có sớm quá không?
+- Nếu phản hồi tức thì thì cái gì trở thành không cần?
+
+Với alp-code, chiều nhỏ là chiều đúng để thử: hệ này có **8 vai và một principal**. Đề xuất
+nào chỉ có nghĩa ở quy mô hàng trăm agent thì là over-engineering ở đây — và YAGNI là luật
+thành văn của repo.
+
+## Cờ đỏ
+
+- "chạy được ở máy tôi" — nhưng chạy thật thì sao?
+- Không biết giới hạn nằm ở đâu.
+- "chắc scale được" mà không có bằng chứng.
+- Bị bất ngờ bởi hành vi lúc chạy thật.
+- Kiến trúc thấy tuỳ tiện, không có lý do cho các lựa chọn.
+
+## Xong thì phải biết
+
+- Hệ vỡ ở đâu — **giới hạn cụ thể**, không phải cảm giác.
+- Cái gì sống sót — phần vững về bản chất.
+- Cái gì phải thiết kế lại — phần phụ thuộc quy mô.
+
+## Nhớ
+
+- Thử **cả hai chiều**, lớn và nhỏ.
+- Đừng đoán — thử. "Chắc là" không phải kết luận.
+- Nhận định rút ra đi vào khuyến nghị, kèm con số cụ thể chứ không kèm tính từ.

package/skills/problem-solving/references/simplification-cascades.md

@@ -0,0 +1,83 @@
+# Thác đơn giản hoá
+
+Tìm **một** nhận định xoá được nhiều thành phần cùng lúc: "nếu điều này đúng thì không cần
+X, Y, Z nữa."
+
+## Nguyên lý
+
+**"Mọi thứ đều là trường hợp riêng của…"** — vế sau câu này, khi điền đúng, làm sập cả một
+mảng phức tạp.
+
+Một trừu tượng mạnh hơn mười thủ thuật khéo.
+
+## Khi nào dùng
+
+| Triệu chứng | Việc phải làm |
+|---|---|
+| cùng một thứ triển khai 5 kiểu | trừu tượng hoá mẫu chung |
+| danh sách special case cứ dài ra | tìm trường hợp tổng quát |
+| luật phức tạp kèm nhiều ngoại lệ | tìm luật không có ngoại lệ |
+| quá nhiều tuỳ chọn config | tìm mặc định đúng cho 95% |
+
+## Cách tìm
+
+Tìm dấu hiệu: nhiều bản triển khai của những khái niệm na ná nhau · xử lý special case rải
+khắp nơi · câu "cần xử lý A, B, C, D theo cách khác nhau" · luật nhiều ngoại lệ.
+
+Rồi hỏi: **"nếu bên dưới chúng là cùng một thứ thì sao?"**
+
+## Ví dụ
+
+**Trừu tượng stream**
+- Trước: handler riêng cho dữ liệu batch / thời gian thực / file / mạng.
+- Nhận định: "mọi đầu vào đều là stream, chỉ khác nguồn."
+- Sau: một bộ xử lý stream, nhiều nguồn stream.
+- Xoá được: 4 bản triển khai.
+
+**Quản trị tài nguyên**
+- Trước: theo dõi session, giới hạn tần suất, kiểm file, pool kết nối — bốn hệ riêng.
+- Nhận định: "tất cả đều là giới hạn tài nguyên theo từng thực thể."
+- Sau: một `ResourceGovernor`, bốn loại tài nguyên.
+
+**Bất biến**
+- Trước: copy phòng thủ, khoá, huỷ cache, phụ thuộc thứ tự thời gian.
+- Nhận định: "coi mọi thứ là dữ liệu bất biến + phép biến đổi."
+- Xoá được: cả một lớp bài toán đồng bộ.
+
+## Quy trình
+
+1. **Liệt kê biến thể** — cái gì đang được làm nhiều kiểu?
+2. **Tìm bản chất** — bên dưới chúng giống nhau ở đâu?
+3. **Rút trừu tượng** — mẫu đó, bỏ hết chi tiết nghiệp vụ, là gì?
+4. **Thử khớp** — mọi trường hợp hiện có có vừa không? Có cái nào phải gượng ép không?
+5. **Đo thác** — bao nhiêu thứ trở thành không cần thiết?
+
+Bước 4 là bước quyết định. Một trừu tượng phải **gượng ép** mới nhét vừa một trường hợp thì
+nó chưa đúng — và nó sẽ đẻ ra special case mới ngay sau khi bạn áp dụng.
+
+## Cờ đỏ — đang bỏ lỡ một thác
+
+- "chỉ cần thêm một case nữa thôi" — lặp mãi không dứt.
+- "chúng giống nhau nhưng khác nhau" — có thể chúng giống thật?
+- Refactor như đập chuột: sửa chỗ này vỡ chỗ kia.
+- File config cứ dài ra.
+- "Đừng đụng vào đó, phức tạp lắm" — phức tạp đang che một mẫu chưa được nhận ra.
+
+## Thước đo
+
+- **Thắng 10 lần, không phải 10%.** Cải thiện 10% thì không phải thác.
+- Đo bằng "xoá được bao nhiêu thứ", không phải "thêm được bao nhiêu".
+- Số dòng xoá > số dòng thêm.
+- Số tuỳ chọn config biến mất.
+
+## Với alp-code
+
+Repo này đã có sẵn nguyên tắc cùng hướng — `README.md`: `scripts/lib/` là **"MỘT nguồn cho
+mỗi loại config"**. Khi đề xuất một thác, kiểm xem nó có đang dựng thêm nguồn thứ hai cho
+cùng một loại dữ liệu không. Nếu có thì đó không phải thác, đó là mảnh vỡ mới.
+
+## Nhớ
+
+- Mẫu thường **đã có sẵn**, chỉ chưa ai gọi tên nó.
+- Thác đúng thì nhìn lại thấy hiển nhiên. Nghe hiển nhiên không phải là dấu hiệu tầm thường.
+- Ghi lại nhận định — nó có giá trị hơn bản refactor nó sinh ra.

package/skills/problem-solving/references/when-stuck.md

@@ -0,0 +1,76 @@
+# Khi bế tắc — chọn kỹ thuật
+
+Mỗi dạng bế tắc cần một kỹ thuật khác. Chẩn đoán sai dạng thì kỹ thuật vô dụng.
+
+## Cây quyết định
+
+```
+BẾ TẮC
+│
+├─ Độ phức tạp phình? Cùng một thứ làm 5 kiểu? Special case mọc thêm mãi?
+│  └─→ Thác đơn giản hoá
+│
+├─ Không tìm được cách hợp? Cách thông thường không đủ?
+│  └─→ Vùng va chạm
+│
+├─ Cùng vấn đề ở nhiều chỗ? Phát minh lại bánh xe? Thấy quen quen?
+│  └─→ Nhận mẫu meta
+│
+├─ Giải pháp thấy gượng? "Buộc phải làm thế này"? Kẹt vì một giả định?
+│  └─→ Bài tập đảo ngược
+│
+├─ Chạy thật có chịu nổi không? Edge case chưa rõ? Không rõ giới hạn?
+│  └─→ Trò chơi quy mô
+│
+└─ Code hỏng? Hành vi sai? Test fail?
+   └─→ KHÔNG phải bế tắc tư duy. Dùng skill `alp-debug`
+```
+
+Nhánh cuối quan trọng: bug không phải bế tắc. Bug là thiếu bằng chứng. Đừng đem kỹ thuật
+gỡ bế tắc ra dùng khi thứ bạn cần chỉ là đọc thêm log.
+
+## Bảng chẩn đoán
+
+| Kiểu bế tắc | Triệu chứng cụ thể | Đọc |
+|---|---|---|
+| **Phức tạp phình** | cùng một thứ 5 kiểu, special case mọc thêm, if/else chồng chất | `simplification-cascades.md` |
+| **Cần đột phá** | cách thông thường không đủ, không tìm được hướng hợp | `collision-zone-thinking.md` |
+| **Mẫu lặp lại** | cùng vấn đề ở nhiều nơi, cảm giác đã gặp rồi | `meta-pattern-recognition.md` |
+| **Kẹt vì giả định** | "buộc phải thế này", không dám chất vấn tiền đề | `inversion-exercise.md` |
+| **Không rõ quy mô** | chạy thật thế nào chưa biết, edge case chưa rõ | `scale-game.md` |
+| **Code hỏng** | hành vi sai, test fail | skill `alp-debug` |
+
+## Cách làm
+
+1. **Chẩn đoán dạng bế tắc** — khớp triệu chứng ở bảng trên.
+2. **Đọc đúng file kỹ thuật đó.**
+3. **Áp dụng theo quy trình, không rút gọn.** Rút gọn là quay về kiểu nghĩ cũ — đúng thứ
+   đang làm bạn bế tắc.
+4. **Ghi lại đã thử gì, kết quả sao.**
+5. **Vẫn tắc** → đổi kỹ thuật khác, hoặc kết hợp.
+
+**Một kỹ thuật một lúc.** Trộn hai kỹ thuật ngay từ đầu thì không biết cái nào có tác dụng.
+
+## Kết hợp
+
+- **Đơn giản hoá + Nhận mẫu meta** — tìm mẫu trước, rồi đơn giản hoá mọi thể hiện.
+- **Va chạm + Đảo ngược** — ép ẩn dụ, rồi lật giả định của chính ẩn dụ đó.
+- **Quy mô + Đơn giản hoá** — cực trị cho thấy nên bỏ cái gì.
+- **Nhận mẫu meta + Quy mô** — nguyên lý chung đem thử ở cực trị.
+
+## Khi không kỹ thuật nào ăn thua
+
+1. **Đóng khung lại vấn đề** — có đang giải đúng bài toán không?
+2. **Giải thích cho người khác** — viết ra thành báo cáo thường tự lộ chỗ hổng.
+3. **Thu nhỏ phạm vi** — giải bản nhỏ hơn trước.
+4. **Chất vấn ràng buộc** — ràng buộc đó có thật, hay chỉ là giả định?
+
+Vẫn không ra thì **nói thẳng là chưa ra**, kèm những gì đã loại trừ. Một câu
+"chưa xác định được, đã loại trừ A, B, C" đáng giá hơn một khuyến nghị đoán bừa —
+Một lượt gỡ bế tắc được mở ra vì độ tin cậy, không vì tốc độ.
+
+## Nhớ
+
+- Khớp triệu chứng với kỹ thuật, đừng chọn theo cái mình quen.
+- Ghi lại đã thử gì — để người đọc không đi lại đường cũ.
+- Bế tắc là tạm thời, không phải vĩnh viễn.