Imported from Pabhassaracitto/In4Up (docs/skills/ci-red-debugging/SKILL.md). Install upstream with npx skills add Pabhassaracitto/In4Up --skill ci-red-debugging. Copyright stays with the author.

SKILL — Debug CI đỏ Flutter khi không có log, không có SDK

0. Chân lý nền tảng

Khi không đọc được log, mỗi lần chạy CI là một oracle trả lời ĐÚNG/SAI cho đúng MỘT giả thuyết (~40–70 giây/vòng với Flutter). Bisect log₂(n) vòng định vị được mọi thủ phan cấp file — miễn là mỗi vòng đổi đúng một biến số.

Sai lầm chết người: đứng yên "suy luận thêm" thay vì push một vòng xác nhận. Suy luận là miễn phí nhưng thường sai; oracle tính bằng phút nhưng luôn đúng.

1. Khảo sát môi trường (làm 1 lần, ~30 giây)

# Host mở/chặn (000 = chặn)
for h in storage.googleapis.com pub.dev api.github.com results-receiver.actions.githubusercontent.com; do
  echo "$h -> $(curl -s -o /dev/null -m 8 -w '%{http_code}' "https://$h/" 2>/dev/null || echo 000)"
done

# Token có quyền gì với repo?
gh api /repos/<owner>/<repo> --jq '.permissions'

# Workflow nào tồn tại?
gh workflow list --all

# Đọc workflow QUA API (kể cả khi git local đang lỗi):
gh api repos/<o>/<r>/contents/.github/workflows/<f>.yml --jq .content | base64 -d

Ba thực tế đã ghi nhận trên Arena (nếu gặp lại thì đỡ mất công khám phá):

• api.github.com, codeload.github.com mở; storage.googleapis.com, pub.dev, results-receiver.actions.githubusercontent.com CHẶN ⇒ không SDK local, không log CI.
• Token GitHub App thường thiếu quyền workflows ⇒ KHÔNG tạo/sửa được file trong .github/workflows/ (push chứa file đó bị reject cả nhánh — hãy tách riêng commit).
• gh run list/watch/view (metadata + step-level ✓/X) HOẠT ĐỘNG — đây là канал chính.

2. Vòng lặp oracle (lệnh chuẩn)

Dùng script kèm theo (tự commit + push + watch + báo step):

docs/skills/ci-red-debugging/scripts/ci_check.sh "ci: bisect B2 - <giả thuyết>"

Hoặc tay:

git add -A && git commit -q -m "ci: bisect <bước> — <giả thuyết>" && git push -q origin <branch>
sleep 15
RID=$(gh run list --workflow=<wf>.yml --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch $RID --exit-status >/dev/null 2>&1; echo "RESULT: $?"    # 0=xanh 1=đỏ
gh run view $RID 2>&1 | grep -E "✓|X|^  - "                           # X step nào?

Luật chơi:

1. Đọc step TRƯỚC, nội dung sau. X Analyze và X Run tests là hai bệnh khác hẳn.
2. Mỗi vòng đúng MỘT biến số.
3. Mỗi commit bisect phải tự thống nhất (compile đứng một mình được) — nếu không, lỗi nhiễu do chính bản bisect làm oracle nói dối.
4. Commit bisect phải chạm path trong paths: filter của workflow, nếu không CI sẽ không chạy mà bạn tưởng "xanh".

3. Cây quyết định

ĐỎ
├─ Step ANALYZE đỏ
│   ├─ B1: Lỗi file trong phạm vi analyze? → rà checklist bẫy (mục 5)
│   ├─ B2: Đoán lint? → KHÔNG đoán — tải rule-set thật:
│   │     gh api repos/flutter/packages/contents/packages/flutter_lints/lib/flutter.yaml?ref=main --jq .content | base64 -d
│   │     (kèm include package:lints/recommended.yaml từ dart-lang/lints)
│   │     flutter_lints 6.0 đã GIẢM mạnh rule — "lint quen thuộc" nhiều khi không còn
│   └─ B3: Bisect NỘI DUNG file: skeleton tối thiểu → trả từng nửa
│
├─ Step RUN TESTS đỏ
│   ├─ T1: Thay TOÀN BỘ test bằng 1 test không-thể-sai (expect(1,1))
│   │     Vẫn đỏ  ⇒ LỖI LOAD SUITE (import-chain compile gãy) → bisect IMPORT
│   │     Xanh   ⇒ ASSERTION sai → bisect theo NỬA nhóm test
│   ├─ Nhớ: flutter analyze ≠ flutter test compile (CFE). Có construct analyzer
│   │     chấp nhận nhưng CFE từ chối — đặc biệt tên class đi qua EXPORT chain.
│   └─ Test "không-thể-sai" mà đỏ = load failure — đây là phép phân biệt rẻ nhất.
│
└─ Step KHÁC (pub get / setup) → thường là hạ tầng: re-run 1 lần rồi hẵng phân tích

4. Giao thức bisect (thứ tự các vòng)

1. Cô lập FILE: git rm file nghi vấn (hoặc dời khỏi paths-filter), push. Đỏ tiếp ⇒ thủ phạm ở file khác. Xanh ⇒ đúng file.
2. Cô lập KHỐI: skeleton tối thiểu của file (class rỗng + 1 hàm), push cho xanh nền, rồi trả nội dung theo NỬA: imports → helpers → bodies.
3. Cô lập IMPORT: skeleton + từng import với usage tối thiểu (nhớ: import không dùng ⇒ warning ⇒ tự đỏ — phải dùng nó). Cảnh giác cặp A + B-mà-export-A.
4. Cô lập TEST: như mục 3 (T1 trước tiên!), rồi chặt nửa nhóm test.
5. Chốt: fix + khôi phục toàn bộ phần đã rút trong MỘT commit, push xác nhận xanh, ghi postmortem vào comment code/ADR + dòng "khi_nào_dùng" của skill này nếu có loại bẫy mới.

Quy ước: commit bisect đặt tên ci: bisect <mã vòng> - <vừa làm gì>; mở PR thì squash-merge để lịch sử sạch.

5. Checklist bẫy ĐÃ TRẢ GIÁ THẬT (rà trước khi push)

6. Khi nào PHẢI lên tiếng với người dùng

• ≥ 5–6 vòng bisect không hội tụ (điều kiện: mỗi vòng phải thu được THÔNG TIN MỚI; 2 vòng liên tiếp không thêm thông tin = đang quay vòng, dừng).
• Cần quyền cao hơn (workflows) hoặc log thật: đưa URL thẳng https://github.com/<o>/<r>/actions/runs/<runId>/job/<jobId> và đề nghị dán đúng đoạn đỏ của step — 30 giây của người dùng thay cho 1 giờ đoán. ✅ ĐÃ THỰC CHIẾN (Task 4): người dùng dán Expected/Actual từ log — fix đúng ngay vòng kế tiếp sau 11 vòng mù. LUÔN dọn "run đầy đủ" trước khi hỏi.
• Agent thường KHÔNG có thị giác — ảnh chụp màn hình log không đọc được: xin dán CHỮ (không phải screenshot), và lưu ý ảnh có thể không tới được filesystem sandbox.
• Remote có commit lạ/không phải của mình ⇒ hỏi trước khi rebase/force.

7. Phòng bệnh

1. File test import tối thiểu — ít import, ít thức gãy load.
2. Fixture JSON đúng format store thật (Hive/SharedPreferences đều là JSON anyway).
3. Float: nghĩ "round-trip qua gì?" trước khi ==.
4. Commit nhỏ, push ngay — push là backup (bẫy 5.5 không mất được thứ đã push).
5. Postmortem bằng comment ngay tại chỗ vỡ — agent kế tiếp (và chính bạn ở turn sau) không trả giá lần hai.

8. Tài liệu liên quan trong repo

• docs/playbooks/ (nếu có) — bản mở rộng của skill này.
• tool/ci/README.md — cách bật workflow khi token thiếu quyền workflows.
• docs/adr/0001-sm2-canonical-formula.md — ví dụ postmortem chuẩn.