systematic-debugging

Tổng quan về skill systematic-debugging

systematic-debugging là một quy trình gỡ lỗi có cấu trúc dành cho agent và developer muốn bớt sửa theo kiểu đoán mò và tìm ra nguyên nhân gốc nhanh hơn. Nguyên tắc cốt lõi của skill systematic-debugging rất đơn giản: phải điều tra trước khi sửa code. Vì vậy, nó đặc biệt phù hợp cho các trường hợp test fail, hành vi flaky, bug production, lỗi build và sự cố integration — những tình huống mà một “quick fix” rất dễ che mất vấn đề thật sự.

Ai là người phù hợp nhất với skill này

Hãy dùng systematic-debugging nếu bạn:

• liên tục gặp các bản sửa không hiệu quả hoặc chỉ sửa được một phần
• đang phải debug dưới áp lực thời gian
• cần một AI assistant chậm lại để điều tra thay vì vá triệu chứng
• muốn có một quy trình lặp lại được cho bug, flaky test và hành vi bất thường

Skill này đặc biệt hữu ích khi lỗi trông có vẻ “rõ ràng”, nhưng bạn vẫn chưa biết vì sao nó lại xảy ra.

Skill này thực sự giúp bạn hoàn thành việc gì

Mục tiêu thật sự không phải là “đưa ra một bản sửa.” Mà là:

1. tái hiện được lỗi,
2. lần ra nguyên nhân,
3. kiểm chứng từng giả thuyết một,
4. rồi mới triển khai bản sửa đúng trọng tâm.

Nghe có vẻ chậm hơn, nhưng thường sẽ giảm đáng kể việc làm lại, các patch thất bại và bug mới phát sinh do sửa theo cảm tính.

Điều gì khiến systematic-debugging khác biệt

Nhiều prompt thông thường nhảy thẳng từ triệu chứng sang giải pháp. systematic-debugging skill thì cố tình không làm vậy. Repo này nhấn mạnh một workflow kiểu “Iron Law”: chưa điều tra ra nguyên nhân gốc thì chưa sửa.

Các file đi kèm cũng khiến skill này thực tế hơn một checklist debug chung chung:

• root-cause-tracing.md hữu ích khi lỗi nhìn thấy được nằm rất xa nguồn gây lỗi thật sự
• condition-based-waiting.md hữu ích cho flaky async test do dùng các khoảng chờ tùy tiện
• defense-in-depth.md giúp biến một bản vá kiểm tra đơn lẻ thành cơ chế phòng ngừa ở mức cấu trúc
• find-polluter.sh giúp cô lập các test làm rò rỉ file hoặc state

Những loại vấn đề phù hợp nhất với systematic-debugging

systematic-debugging for Debugging đặc biệt hợp với:

• test fail mà bạn chưa giải thích được nguyên nhân
• flaky test trong CI
• bug mà các bản sửa trước đó không giải quyết dứt điểm
• lỗi xuất hiện rất sâu trong stack
• state sai, file bị rò rỉ, path sai, race condition và các vấn đề liên quan tới timing

Khi nào skill này không thực sự phù hợp

Chỉ nên bỏ qua nếu bài toán đó thực ra không phải debug, ví dụ:

• làm feature tương đối thẳng
• refactor thường quy mà không có hành vi lỗi nào cần giải thích
• thay đổi thuần về mặt hiển thị

Dù vậy, nếu bạn đang xử lý một “hành vi bất thường”, thì systematic-debugging vẫn thường là điểm bắt đầu an toàn hơn.

Cách dùng skill systematic-debugging

Bối cảnh cài đặt cho systematic-debugging

Nếu bạn dùng mô hình Skills CLI như trong hệ sinh thái này, hãy cài bằng:

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

Sau đó, bạn có thể gọi nó từ môi trường agent của mình hoặc dùng quy trình thủ công bằng cách đọc các file nguồn trong thư mục skill.

Hãy đọc các file này trước tiên

Để có một systematic-debugging guide nhanh và nhiều tín hiệu, hãy đọc theo thứ tự này:

1. skills/systematic-debugging/SKILL.md
2. skills/systematic-debugging/root-cause-tracing.md
3. skills/systematic-debugging/condition-based-waiting.md
4. skills/systematic-debugging/defense-in-depth.md
5. skills/systematic-debugging/find-polluter.sh

Lý do nên đọc theo thứ tự đó:

• SKILL.md đưa ra quy trình 4 giai đoạn bắt buộc
• root-cause-tracing.md hữu ích khi triệu chứng chỉ xuất hiện rất xa về phía sau
• condition-based-waiting.md đưa ra một mẫu sửa cụ thể cho flaky async test
• defense-in-depth.md giúp gia cố bản sửa cuối cùng
• find-polluter.sh là công cụ thực dụng để cô lập test gây ô nhiễm

systematic-debugging cần bạn cung cấp những đầu vào nào

Chất lượng systematic-debugging usage phụ thuộc rất nhiều vào đầu vào bạn cung cấp. Hãy đưa cho skill:

• thông báo lỗi chính xác
• stack trace
• các bước tái hiện lỗi
• hành vi kỳ vọng so với hành vi thực tế
• chi tiết môi trường như OS, runtime, test runner, chỉ lỗi trên CI hay chỉ lỗi local
• các thay đổi code gần đây
• lỗi là deterministic hay flaky
• những gì bạn đã thử

Nếu thiếu các dữ liệu này, model sẽ dễ suy đoán hơn thay vì bám vào bằng chứng.

Biến một bug report sơ sài thành prompt mạnh hơn

Prompt yếu:

Test is failing. Help fix it.

Prompt tốt hơn:

Use systematic-debugging on this failing test. Do not propose a fix until root cause investigation is complete. Here is the exact error, stack trace, reproduction command, recent changes, and the one behavior difference between local and CI. Identify likely root causes, suggest the minimum investigation steps, and keep hypotheses separate.

Prompt này hiệu quả hơn vì nó yêu cầu đầu ra điều tra trước khi đi vào triển khai bản sửa.

Một mẫu prompt thực tế

Hãy dùng cấu trúc này cho systematic-debugging usage:

• Issue: cái gì đang fail
• Reproduction: câu lệnh hoặc các bước tái hiện chính xác
• Evidence: log, trace, screenshot, assertion bị fail
• Scope: local, CI, một máy, hay mọi môi trường
• Recent changes: commit, nâng version dependency, chỉnh config
• Constraints: không được đổi API, cần patch tối thiểu, có deadline, v.v.
• Request: điều tra nguyên nhân gốc trước, sau đó mới đề xuất một bản sửa

Ví dụ:

Use systematic-debugging for this Jest failure. Repro: npm test src/foo.test.ts. Error: Timeout waiting for TOOL_RESULT event after 5000ms. It fails in CI and under parallel runs, not always locally. We recently changed thread event handling. First investigate root cause, then propose one focused fix and one validation plan.

Hãy đi theo đúng thứ tự của quy trình 4 giai đoạn

Repo này xoay quanh 4 giai đoạn. Trong thực tế, bạn nên dùng như sau:

1. Điều tra nguyên nhân gốc
   Đọc kỹ lỗi, tái hiện ổn định, kiểm tra những gì vừa thay đổi và thu thập bằng chứng.
2. Phân tích pattern
   Tìm các pattern liên quan đến timing, môi trường, dạng dữ liệu đầu vào, rò rỉ state hoặc chuỗi gọi hàm.
3. Kiểm chứng giả thuyết
   Mỗi lần chỉ đưa ra một cách giải thích và kiểm tra nó. Tránh thay đổi nhiều biến cùng lúc.
4. Triển khai
   Chỉ khi bằng chứng đã ủng hộ nguyên nhân, mới sửa và xác minh lại.

Nếu Giai đoạn 1 làm hời hợt, mọi bước phía sau đều sẽ kém đi.

Cách dùng systematic-debugging cho flaky test

Repo này hỗ trợ phần này thực tế hơn thường thấy. Nếu một test phụ thuộc vào sleep, setTimeout hoặc các khoảng chờ đặt đại, hãy xem condition-based-waiting.md và condition-based-waiting-example.ts.

Chuyển đổi cốt lõi là:

• pattern kém: đoán xem tác vụ async cần bao lâu
• pattern tốt hơn: chờ đến khi điều kiện xác nhận việc hoàn tất thực sự xảy ra

Điều này quan trọng vì nhiều lỗi tưởng như “ngẫu nhiên” thực ra là race condition bị che đi bởi cách đoán timing.

Cách dùng systematic-debugging khi triệu chứng nằm ở phía hạ lưu

Nếu lỗi xuất hiện sâu trong stack hoặc rất xa nơi dữ liệu sai bắt đầu phát sinh, hãy dùng root-cause-tracing.md. Workflow là:

• xác định dòng code fail trực tiếp
• lần ngược lên một caller
• tiếp tục lần ngược cho tới khi tìm thấy nơi state sai xuất hiện lần đầu
• sửa tại nguồn, không chỉ sửa ở chỗ crash

Đây là một trong những phần giá trị nhất của systematic-debugging skill, vì rất nhiều bug chỉ là triệu chứng của một state không hợp lệ xuất hiện từ trước.

Cách dùng công cụ tìm polluter

Với các test để lại file, thư mục hoặc state sau khi chạy, find-polluter.sh đáng để đọc trước khi bạn tự chế một vòng lặp khác.

Mẫu dùng:
./find-polluter.sh <file_or_dir_to_check> <test_pattern>

Ví dụ lấy từ script:
./find-polluter.sh '.git' 'src/**/*.test.ts'

Công cụ này đặc biệt hữu ích khi lỗi đến từ test pollution ẩn, chứ không phải từ test đang hiện ra là bị fail.

Workflow thường cho kết quả tốt nhất với systematic-debugging

Một workflow đáng tin cậy cho systematic-debugging install và lần sử dụng đầu tiên:

1. cài skill
2. đọc SKILL.md
3. thu thập bằng chứng lỗi chính xác
4. yêu cầu agent điều tra mà chưa sửa
5. chọn giả thuyết được bằng chứng ủng hộ mạnh nhất
6. chỉ kiểm tra giả thuyết đó
7. triển khai một bản sửa tập trung
8. thêm lớp xác thực hoặc defense-in-depth nếu bug bắt nguồn từ dữ liệu không hợp lệ hoặc có nhiều đường đi vào

Cách này ngăn lỗi phổ biến nhất: sửa code trước khi hiểu chuyện gì đang hỏng.

Không nên dùng skill này theo cách nào

Đừng yêu cầu systematic-debugging:

• brainstorm nhiều cách sửa ngay lập tức
• viết lại những vùng lớn trước khi tái hiện được bug
• “chỉ cần làm cho test pass” mà không giải thích
• vá nhiều nguyên nhân nghi ngờ cùng một lúc

Những lối tắt đó đi ngược trực tiếp với thiết kế của skill và làm giảm chất lượng đầu ra.

Câu hỏi thường gặp về skill systematic-debugging

systematic-debugging chỉ dành cho bug phức tạp thôi sao?

Không. Quan điểm của repo là ngay cả bug đơn giản cũng có nguyên nhân gốc. Skill này phát huy giá trị mạnh nhất khi vấn đề trông có vẻ đơn giản đến mức khiến bạn muốn vá nhanh cho xong.

Nó khác gì so với một prompt debug thông thường?

Prompt thông thường thường ưu tiên tốc độ và chấp nhận các bản sửa mang tính suy đoán. systematic-debugging buộc model tách riêng điều tra, giả thuyết và triển khai. Kết quả thường là ít patch sai hơn và phần giải thích cũng tốt hơn.

systematic-debugging có thân thiện với người mới không?

Có, nếu bạn cung cấp được bằng chứng cụ thể. Quy trình này khá nghiêm ngặt, nhưng các bước đều dễ hiểu: tái hiện, kiểm tra, lần vết, thử từng giả thuyết, rồi mới sửa. Người mới thậm chí còn có thể hưởng lợi nhiều hơn vì nó ngăn kiểu thử-sai ngẫu hứng.

Khi nào tôi không nên dùng systematic-debugging?

Đừng dùng nó làm mẫu chính cho:

• lên ý tưởng feature
• brainstorm kiến trúc
• sinh code không liên quan đến một lỗi cụ thể
• chỉnh sửa thuần về giao diện khi không có hành vi hỏng cần giải thích

Hãy dùng khi có thứ gì đó đang sai và bạn cần tìm ra nguyên nhân, chứ không chỉ cần một patch.

systematic-debugging có giúp xử lý lỗi chỉ xảy ra trên CI không?

Có. Nó rất phù hợp với các lỗi chỉ xuất hiện trên CI hoặc nhạy với tải, vì nó buộc bạn so sánh môi trường, tái tạo điều kiện xảy ra lỗi và kiểm tra các giả định về timing và state thay vì đoán bừa.

Nó có giúp với flaky async test không?

Có, và repo này làm phần đó tốt hơn mức trung bình. condition-based-waiting.md cùng file ví dụ TypeScript đưa ra con đường rất cụ thể để rời khỏi các khoảng chờ tùy tiện và chuyển sang đồng bộ hóa theo điều kiện thực tế.

Skill này có kèm công cụ hay chỉ là hướng dẫn?

Phần lớn là hướng dẫn về quy trình, nhưng có kèm một số file hỗ trợ rất cụ thể. Trợ thủ thực tế nhất là find-polluter.sh, và ví dụ về condition-based waiting có thể tái sử dụng trực tiếp trong một số thiết lập test TypeScript.

Tôi có thể dùng systematic-debugging với bất kỳ stack nào không?

Phần lớn là có. Phương pháp cốt lõi không phụ thuộc stack. Ví dụ trong repo thiên về TypeScript, shell và workflow test, nhưng bản thân quy trình điều tra vẫn áp dụng được trên nhiều ngôn ngữ và framework.

Cách cải thiện skill systematic-debugging

Cung cấp bằng chứng tốt hơn trước khi yêu cầu sửa

Đòn bẩy lớn nhất là chất lượng đầu vào. Để có kết quả systematic-debugging tốt hơn, hãy kèm theo:

• một câu lệnh tái hiện chính xác
• một khối lỗi chính xác
• một test hoặc file lỗi tối thiểu
• những gì vừa thay đổi gần đây
• lỗi có tái hiện được mọi lúc hay không

Như vậy skill sẽ làm việc dựa trên bằng chứng thay vì suy luận phỏng đoán.

Yêu cầu đầu ra điều tra trước khi đi vào triển khai

Một prompt tốt sẽ chặn việc sửa quá sớm một cách rõ ràng. Ví dụ:

Use systematic-debugging. First produce root-cause investigation findings and the top 2 hypotheses with evidence for each. Do not suggest code changes yet.

Điều này nâng chất lượng câu trả lời vì nó tạo ra một điểm chặn giữa việc đọc triệu chứng và chỉnh sửa code.

Buộc mỗi lần chỉ xét một giả thuyết

Một kiểu thất bại phổ biến là trộn nhiều nguyên nhân khả dĩ vào cùng một patch. Hãy yêu cầu:

• giả thuyết dẫn đầu
• bài kiểm tra nhỏ nhất có thể bác bỏ nó
• kết quả nào sẽ xác nhận nó

Cách này giữ workflow bám sát đúng ý đồ của skill.

Cải thiện prompt cho các tình huống flaky test

Khi dùng systematic-debugging for Debugging cho flaky test, hãy cung cấp:

• tần suất pass/fail
• lỗi có tương quan với chạy song song hoặc CI hay không
• có dùng sleeps, waits, retries hoặc polling nào không
• chính xác test đang cố quan sát event hoặc state nào

Nhờ đó model sẽ dễ nhận ra khi nào condition-based-waiting.md là tài liệu đi kèm phù hợp.

Dùng các file sát nguồn, đừng chỉ đọc mỗi SKILL.md

Nếu đầu ra đầu tiên còn chung chung, hãy trỏ model đến các tài liệu hỗ trợ:

• root-cause-tracing.md cho triệu chứng nằm ở phía hạ lưu
• condition-based-waiting.md cho lỗi timing/race
• defense-in-depth.md cho chiến lược xác thực
• find-polluter.sh cho test pollution

Skill hoạt động tốt hơn khi agent tận dụng các tài liệu chuyên biệt đi kèm, thay vì chỉ bám vào workflow tổng quát.

Thu hẹp phạm vi sau lượt đầu tiên

Nếu kết quả đầu còn quá rộng, hãy tinh chỉnh bằng:

• subsystem chính xác cần kiểm tra
• ranh giới nghi ngờ nơi dữ liệu xấu đi vào
• commit đầu tiên mà lỗi xuất hiện
• cách tái hiện lỗi nhỏ nhất đang fail

Prompt debug quá rộng thường tạo ra kế hoạch debug cũng quá rộng. Phạm vi hẹp hơn sẽ cho công việc truy nguyên nhân gốc tốt hơn.

Cải thiện bản sửa cuối cùng, không chỉ chẩn đoán

Sau khi tìm ra nguyên nhân gốc, hãy yêu cầu:

• bản sửa tối thiểu
• một regression test
• một lớp xác thực để ngăn lỗi tái diễn

Đây là lúc defense-in-depth.md phát huy tác dụng. Nếu bug đến từ input không hợp lệ hoặc từ các giả định có thể bị đi vòng qua, một patch đơn lẻ có thể là chưa đủ.

Hãy để ý các kiểu thất bại phổ biến này

systematic-debugging usage kém hiệu quả thường đến từ:

• thiếu nội dung lỗi đầy đủ
• không có cách tái hiện ổn định
• yêu cầu sửa quá sớm
• thay đổi nhiều thứ giữa các lần chạy test
• coi cách giải thích nghe có vẻ hợp lý đầu tiên như là đã được chứng minh

Nếu tránh được những điểm đó, skill này sẽ có giá trị cao hơn hẳn một prompt “debug cái này giúp tôi” kiểu chung chung.