systematic-debugging

Tổng quan

systematic-debugging là gì?

Kỹ năng systematic-debugging là một quy trình có cấu trúc gồm 4 giai đoạn để debug mọi loại sự cố kỹ thuật: lỗi test, bug production, flaky test, vấn đề hiệu năng, lỗi build hoặc lỗi tích hợp.

Thay vì thử "một bản vá nhanh" hoặc sửa code ngay tại dòng báo lỗi đầu tiên, kỹ năng này buộc bạn phải điều tra nguyên nhân gốc rễ trước, sau đó mới thiết kế và kiểm chứng một bản sửa bền vững. Nó được hỗ trợ bởi các pattern và script thực tế từ một codebase thật, bao gồm các helper condition-based waiting trong TypeScript và một Bash script để tìm test polluter.

Nguyên tắc cốt lõi và Iron Law

Trọng tâm của systematic-debugging rất đơn giản:

• Nguyên tắc cốt lõi: Luôn tìm nguyên nhân gốc rễ trước khi cố gắng sửa. Những bản sửa chỉ nhắm vào triệu chứng được xem là thất bại.

• Iron Law:

  NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
  

Nếu bạn chưa hoàn thành giai đoạn điều tra, bạn không được đề xuất hay áp dụng bất kỳ bản sửa nào. Quy tắc này được thiết kế để chống lại áp lực thời gian, đoán mò và những lời biện minh kiểu "chỉ lần này thôi".

Kỹ năng này dành cho ai?

systematic-debugging hướng đến:

• Lập trình viên làm việc với dự án JavaScript/TypeScript muốn có các bản sửa đáng tin cậy, lặp lại được
• Kỹ sư Test và QA phải xử lý hành vi flaky, timeout ngẫu nhiên và trạng thái test bị ô nhiễm
• Kỹ sư CI/CD và tooling cần chẩn đoán lỗi build hoặc lỗi tích hợp xảy ra không ổn định
• Tech lead và reviewer muốn có một quy trình debug chung, chặt chẽ cho cả nhóm

Kỹ năng này đặc biệt phù hợp nếu bạn ưu tiên phân tích nguyên nhân gốc rễ chất lượng cao hơn là vá nhanh triệu chứng.

Kỹ năng này giải quyết vấn đề gì?

Hãy dùng kỹ năng systematic-debugging khi bạn cần:

• Điều tra lỗi test liên tục quay lại dù đã "sửa" nhiều lần
• Lần theo flaky test phụ thuộc vào timeout tùy ý hoặc race condition
• Hiểu hành vi bất ngờ thay vì chỉ tắt thông báo lỗi
• Chẩn đoán vấn đề hiệu năng hoặc các luồng xử lý chậm, nhạy cảm về thời gian
• Debug lỗi build hoặc tích hợp chỉ xảy ra trong CI hoặc dưới tải
• Tìm ra test làm ô nhiễm trạng thái hoặc để lại file/thư mục không mong muốn

Repository còn bao gồm:

• condition-based-waiting.md và condition-based-waiting-example.ts để thay setTimeout/sleep bằng condition-based waiting vững chắc trong TypeScript
• defense-in-depth.md để thêm validation ở nhiều tầng, khiến một số loại bug trở nên bất khả thi về mặt cấu trúc
• find-polluter.sh, một Bash helper giúp tìm chính xác test tạo ra file hoặc trạng thái không mong muốn
• root-cause-tracing.md để truy vết lỗi ngược qua call chain đến nguồn gốc thực sự

Khi nào systematic-debugging là lựa chọn phù hợp?

systematic-debugging đặc biệt phù hợp khi:

• Bạn đang chịu áp lực thời gian và dễ bị cám dỗ đoán mò cách sửa
• Một vấn đề cứ tái xuất hiện dù đã thử nhiều lần sửa
• Bạn muốn có quy trình debug lặp lại được cho bản thân hoặc cả đội
• Bạn đang ổn định một bộ test flaky hoặc dọn dẹp môi trường test bị ô nhiễm

Nó có thể ít phù hợp hơn nếu:

• Bạn chỉ cần một lần tạo code nhanh hoặc refactor nhỏ mà không cần điều tra
• Bạn đang debug ngoài phạm vi kỹ thuật được mô tả (ví dụ: vấn đề quy trình phi kỹ thuật)
• Bạn không muốn tuân theo quy trình từng bước và thích thử nghiệm ngẫu hứng

Nếu mục tiêu của bạn là "vá nhanh bây giờ, chấp nhận sửa lại sau", quy trình này sẽ có vẻ quá nghiêm ngặt. Nếu mục tiêu của bạn là "sửa một lần cho đúng", systematic-debugging được thiết kế cho bạn.

Cách sử dụng

Cài đặt và thiết lập

Để cài kỹ năng systematic-debugging vào một agent hoặc môi trường công cụ tương thích, hãy dùng lệnh npx sau:

npx skills add https://github.com/obra/superpowers --skill systematic-debugging
``

Lệnh này sẽ kéo definition của kỹ năng cùng các tài liệu và script hỗ trợ từ repository `obra/superpowers` dưới thư mục `skills/systematic-debugging`.

Sau khi cài đặt:

1. Mở kỹ năng `systematic-debugging` trong agent hoặc giao diện kỹ năng của bạn.
2. Đảm bảo workspace của bạn có quyền truy cập vào repository dự án, các lệnh test và log.
3. Kiểm tra bạn có thể xem các markdown guide và script đi kèm:
   - `SKILL.md`
   - `condition-based-waiting.md`
   - `defense-in-depth.md`
   - `root-cause-tracing.md`
   - `find-polluter.sh`

### Các file và thành phần quan trọng
Cho quyết định cài đặt và sử dụng hàng ngày, các file sau là quan trọng nhất:

- **`SKILL.md`** – Mô tả đầy đủ quy trình debug hệ thống 4 giai đoạn, các quy tắc và anti-pattern. Đây là phần lõi của kỹ năng.
- **`condition-based-waiting.md`** – Giải thích cách thay các timeout tùy ý trong test bằng condition-based waiting.
- **`condition-based-waiting-example.ts`** – Các tiện ích TypeScript như `waitForEvent` triển khai condition-based waiting với `ThreadManager` và event type.
- **`defense-in-depth.md`** – Trình bày cách áp dụng validation nhiều tầng (entry point, business logic, environment guard, logging) để cả một lớp bug trở nên không thể xảy ra.
- **`find-polluter.sh`** – Bash script chạy lần lượt các test để tìm ra test nào tạo ra một đường dẫn cụ thể (state pollution).
- **`root-cause-tracing.md`** – Hướng dẫn truy vết bug từ stack trace quay lại trigger ban đầu, rồi kết hợp với defense-in-depth.
- **`CREATION-LOG.md`** – Meta-log giải thích cách framework được trích xuất và củng cố; hữu ích để hiểu ý đồ thiết kế, ít quan trọng hơn cho sử dụng hàng ngày.

Với lập trình viên **JavaScript/TypeScript**, file ví dụ TypeScript và Bash script thường có thể được dùng lại hoặc điều chỉnh trực tiếp trong dự án của bạn.

### Vận hành quy trình 4 giai đoạn
Quy trình `systematic-debugging` được tổ chức thành 4 giai đoạn bắt buộc (mô tả trong `SKILL.md`). Bạn phải hoàn thành từng giai đoạn trước khi chuyển sang giai đoạn tiếp theo.

#### Giai đoạn 1 – Điều tra nguyên nhân gốc rễ
Trước khi chạm vào bất kỳ code, cấu hình hay test nào:

- **Đọc kỹ thông báo lỗi và log.**
  - Không lướt qua stack trace hay cảnh báo.
  - Ghi lại số dòng, đường dẫn file và mã lỗi.
- **Tái hiện vấn đề một cách ổn định.**
  - Xác định một lệnh tái hiện tối thiểu, đáng tin cậy.
  - Ghi chú những input và yếu tố môi trường cần thiết.

Bạn không đề xuất hay triển khai bản sửa ở giai đoạn này. Mục tiêu là hiểu: chính xác cái gì đang hỏng, ở đâu, và trong điều kiện nào.

#### Giai đoạn 2 – Phân tích pattern
Sau khi tái hiện được vấn đề ổn định:

- Thay đổi từng yếu tố một (input, cấu hình, môi trường) để xem điều gì làm thay đổi kết quả.
- Tìm các ranh giới: giá trị hoặc điều kiện khiến hành vi từ pass chuyển sang fail.
- Dùng log, assertion hoặc instrumentation tạm thời để thu hẹp đường dẫn bị lỗi.

Kết thúc Giai đoạn 2, bạn nên hiểu hình dạng của vấn đề và các điều kiện kích hoạt nó, chứ không chỉ là thông báo lỗi cuối cùng.

#### Giai đoạn 3 – Giả thuyết và thiết kế
Lúc này bạn có thể hình thành giả thuyết:

- Nêu rõ bạn tin nguyên nhân gốc rễ là gì (luồng dữ liệu, thiếu validation, vấn đề timing, đường dẫn sai, v.v.).
- Thiết kế một thay đổi **tập trung, đơn lẻ** để xử lý trực tiếp nguyên nhân đó.
- Lên kế hoạch cách bạn sẽ kiểm chứng giả thuyết bằng các bước tái hiện đã có.

Nếu giả thuyết sai, bạn quay lại điều tra/phân tích thay vì chồng thêm các bản sửa mang tính đoán mò.

#### Giai đoạn 4 – Triển khai và kiểm chứng
Chỉ sau khi đã có giả thuyết rõ ràng, bạn mới sửa code hoặc cấu hình:

- Áp dụng thay đổi nhỏ nhất xử lý trực tiếp nguyên nhân gốc rễ.
- Chạy lại lệnh tái hiện tối thiểu rồi đến toàn bộ test suite.
- Tham khảo:
  - `defense-in-depth.md` để thêm validation ở nhiều tầng
  - `root-cause-tracing.md` để đảm bảo bạn đang sửa đúng nguồn gốc
- Xác nhận bản sửa vững chắc (ví dụ: hoạt động tốt dưới tải, trong CI và với các edge case đã tìm trong Giai đoạn 2).

Nếu bản sửa không hoạt động như mong đợi, bạn **không** chồng thêm thay đổi; hãy quay lại các giai đoạn trước.

### Dùng các tiện ích debug trong dự án của bạn

#### Condition-based waiting cho flaky test (JavaScript/TypeScript)
Flaky test dựa vào `setTimeout` hoặc `sleep` thường bị hỏng khi máy chạy chậm hơn, nhanh hơn hoặc dưới tải. `condition-based-waiting.md` và `condition-based-waiting-example.ts` đưa ra một pattern tốt hơn: chờ đến khi điều kiện bạn quan tâm được thỏa mãn.

Quy trình chuyển đổi điển hình:

```typescript
// ❌ Trước đây: đoán thời gian
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();

// ✅ Sau: chờ theo điều kiện
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();

File condition-based-waiting-example.ts cung cấp các helper như:

export function waitForEvent(
  threadManager: ThreadManager,
  threadId: string,
  eventType: LaceEventType,
  timeoutMs = 5000
): Promise<LaceEvent> { /* ... */ }

Hãy điều chỉnh các pattern này cho hạ tầng test của bạn:

1. Sao chép hoặc tự triển khai lại các tiện ích vào test helper của dự án.
2. Thay các lệnh setTimeout/sleep tùy ý bằng condition-based wait.
3. Chạy lại test suite để xác nhận mức độ flaky giảm xuống.

Điều này trực tiếp hỗ trợ mục tiêu của systematic-debugging là loại bỏ nguyên nhân gốc rễ thay vì kéo dài timeout một cách ngẫu nhiên.

Tìm test gây ô nhiễm với find-polluter.sh

Nếu test của bạn để lại file, thư mục thừa hoặc làm ô nhiễm trạng thái, find-polluter.sh giúp tìm chính xác test chịu trách nhiệm.

Cách dùng (từ thư mục gốc dự án, điều chỉnh tham số cho phù hợp):

./find-polluter.sh <file_or_dir_to_check> <test_pattern>

# Ví dụ
./find-polluter.sh '.git' 'src/**/*.test.ts'

Script sẽ:

• Tìm các file test khớp với pattern
• Chạy từng file một với npm test <file>
• Sau mỗi lần chạy, kiểm tra xem file hoặc thư mục mục tiêu đã tồn tại chưa
• Dừng và báo test đầu tiên tạo ra nó, kèm lệnh để bạn chạy lại và kiểm tra test đó

Công cụ này phù hợp với Giai đoạn 1 và Giai đoạn 2 của systematic-debugging vì nó cung cấp cách tái hiện và cô lập state pollution một cách đáng tin cậy.

Áp dụng validation defense-in-depth

Khi điều tra cho thấy bug xuất phát từ dữ liệu hoặc giả định không hợp lệ, defense-in-depth.md khuyến nghị đặt validation ở nhiều tầng:

• Entry point validation – Loại bỏ input sai rõ ràng ngay tại boundary (API, CLI, UI handler).
• Business logic validation – Đảm bảo dữ liệu hợp lý với từng nghiệp vụ cụ thể.
• Environment guard – Ngăn thao tác nguy hiểm ở sai môi trường hoặc sai đường dẫn.
• Diagnostic logging – Cung cấp ngữ cảnh hữu ích nếu vẫn có thứ gì lọt qua.

Ví dụ, validate tham số workingDirectory:

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
  }
  // ... proceed
}

Hãy dùng các pattern này khi triển khai bản sửa ở Giai đoạn 4 để đảm bảo bug khó có thể quay lại qua một nhánh code khác.

Khi nào không nên dùng kỹ năng này

Có thể bạn nên bỏ qua hoặc hoãn dùng systematic-debugging nếu:

• Bạn đang prototyping và chấp nhận code tạm, bug tạm
• Vấn đề rất đơn giản và đã hiểu rõ (ví dụ, một lỗi typo rõ ràng phát hiện trong khi dev) và không xứng đáng áp dụng đầy đủ quy trình 4 giai đoạn
• Bạn chỉ cần các tiện ích mẫu (như condition-based wait) chứ không cần toàn bộ quy trình

Ngay cả trong các trường hợp này, Iron Law vẫn là một điểm tự kiểm tra hữu ích: nếu bạn nhận ra mình đang chồng nhiều bản sửa đoán mò, đã đến lúc chuyển sang systematic-debugging.

FAQ

systematic-debugging thực sự thay đổi workflow của tôi như thế nào?

Thay vì nhảy thẳng từ thông báo lỗi sang sửa code, systematic-debugging buộc bạn đi qua điều tra, phân tích pattern và giả thuyết trước khi triển khai. Trên thực tế điều này có nghĩa là:

• Bạn luôn thu thập một cách tái hiện lỗi đáng tin cậy trước khi sửa code
• Bạn thay đổi điều kiện để hiểu không gian vấn đề
• Bạn viết một bản sửa tập trung cho mỗi giả thuyết đã được kiểm chứng

Kết quả là ít phải revert hơn, ít regression ẩn hơn và thời gian debug dễ dự đoán hơn.

Tôi cài kỹ năng systematic-debugging như thế nào?

Dùng lệnh npx skills:

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

Sau khi cài đặt, mở kỹ năng trong agent hoặc thư mục kỹ năng của bạn, rồi đọc SKILL.md để nắm toàn bộ quy trình cùng các file markdown hỗ trợ cho pattern và ví dụ.

systematic-debugging có hỗ trợ debug JavaScript và TypeScript không?

Có. Dù bản thân framework là agnostic về ngôn ngữ, repository cung cấp các tiện ích cụ thể cho JavaScript/TypeScript:

• condition-based-waiting-example.ts cho condition-based waiting trong test
• Các pattern trong defense-in-depth.md và root-cause-tracing.md minh họa bằng ví dụ TypeScript
• find-polluter.sh, mặc định giả định dùng npm test và hoạt động tốt với các test runner JS/TS điển hình

Bạn có thể điều chỉnh các tiện ích này theo cấu trúc và tooling dự án của mình.

Tôi có thể dùng systematic-debugging cho tự động hóa flaky test không?

Có. Đây là một trong những use case mạnh nhất. Hãy kết hợp:

• Quy trình 4 giai đoạn từ SKILL.md để điều tra và hiểu nguyên nhân flaky
• condition-based-waiting.md và ví dụ TypeScript để thay đoán thời gian bằng condition-based wait
• find-polluter.sh để tìm các test làm ô nhiễm trạng thái hoặc tạo file bất ngờ

Kết hợp lại, những công cụ này giúp bạn biến test không ổn định thành các kiểm thử ổn định, có tính quyết định.

systematic-debugging chỉ dành cho test, hay dùng được cho bug production nữa?

Quy trình này áp dụng cho mọi vấn đề kỹ thuật:

• Lỗi test và flaky test
• Bug và sự cố production
• Vấn đề hiệu năng
• Lỗi build và lỗi tích hợp

Các ví dụ và tiện ích thiên về workflow test và phát triển, nhưng các giai đoạn và nguyên tắc thì được thiết kế rõ ràng để bao phủ cả kịch bản production.

Nếu tôi đang chịu áp lực thời gian và chỉ cần sửa nhanh thì sao?

Kỹ năng này được viết ra chính để chống lại xu hướng "sửa nhanh một phát". Nó chỉ ra rằng:

• Vội sửa mà không điều tra nguyên nhân gốc rễ sẽ dẫn tới loay hoay và phải làm lại
• Những bản sửa chỉ xử lý triệu chứng thường tạo ra vấn đề mới

Trên thực tế, dành vài phút để làm đúng Giai đoạn 1 và Giai đoạn 2 thường tiết kiệm thời gian tổng thể, ngay cả trong tình huống khẩn cấp.

Tôi có phải tuân theo đủ cả 4 giai đoạn mọi lần không?

Mục tiêu của systematic-debugging là bỏ qua giai đoạn chỉ là ngoại lệ, không phải thói quen. Với những vấn đề nhỏ, đã hiểu tường tận (ví dụ, một refactor nhỏ nơi bạn nhìn là thấy lỗi ngay), bạn có thể rút gọn bước. Nhưng nếu:

• Vấn đề lặp đi lặp lại
• Bạn chưa thực sự hiểu vì sao nó xảy ra
• Các bản sửa trước đó đã thất bại

…thì rất nên áp dụng đầy đủ quy trình 4 giai đoạn.

Root-cause tracing liên quan gì đến defense-in-depth?

root-cause-tracing.md giúp bạn lần theo bug từ lỗi nhìn thấy được ngược qua call chain tới trigger ban đầu. Sau đó defense-in-depth.md cho thấy cách ngăn các bug tương tự bằng cách:

• Sửa tại đúng nguồn gốc
• Thêm validation ở nhiều lớp khác nhau

Ví dụ, nếu git init bị lỗi ở thư mục sai, phần tracing sẽ cho bạn thấy function nào truyền vào đường dẫn sai, còn defense-in-depth sẽ bổ sung validation và guard để đường dẫn không hợp lệ bị từ chối sớm hơn.

Tôi có thể dùng kỹ năng này mà không copy bất kỳ đoạn code nào từ repo không?

Có. Giá trị cốt lõi của systematic-debugging là quy trình debug có cấu trúc mô tả trong SKILL.md. Bạn có thể:

• Làm theo các giai đoạn và quy tắc trực tiếp trong môi trường của mình
• Áp dụng các pattern điều tra và phân tích cho mọi ngôn ngữ hoặc stack

Các helper TypeScript và Bash chỉ là công cụ tăng tốc tùy chọn, đặc biệt hữu ích cho JS/TS và môi trường giống Unix.

Tôi có thể xem mọi thứ trong systematic-debugging ở đâu?

Sau khi cài đặt, hãy mở phần Files hoặc repository view cho obra/superpowers dưới skills/systematic-debugging. Các file quan trọng nên xem gồm:

• SKILL.md
• condition-based-waiting.md
• condition-based-waiting-example.ts
• defense-in-depth.md
• root-cause-tracing.md
• find-polluter.sh

Những file này mang đến cho bạn toàn bộ workflow systematic-debugging cùng các công cụ cụ thể để debug và ổn định test.