Fix — Sửa bug

Phân tích và sửa bug tự động. Tuân thủ nguyên tắc: tìm root cause TRƯỚC, fix SAU. Tự động detect loại bug và chọn strategy phù hợp.

Cú pháp

/fix "mô tả bug"               # Auto-detect loại bug → routing
/fix:fast                       # Fix bug đơn giản
/fix:hard                       # Fix bug phức tạp (dùng subagents)
/fix:test                       # Fix failing tests
/fix:ci                         # Fix CI/CD failures
/fix:types                      # Fix TypeScript errors
/fix:ui                         # Fix UI issues
/fix:logs                       # Phân tích logs + fix
/fix:parallel                   # Fix nhiều issues song song

Luồng hoạt động bên trong

Khi bạn gõ /fix "API returns 500 when creating order", đây là 6 bước xảy ra:
1

Bước 1: Scout (BẮT BUỘC — không bao giờ skip)

Kích hoạt ck:scout skill HOẶC spawn 2-3 Explore subagents song song. Mục tiêu: hiểu codebase TRƯỚC khi đưa ra giả thuyết.
  • Tìm: affected files, dependencies, related tests, recent changes (git log)
  • Đọc ./docs nếu chưa quen project
Output: Step 1: Scouted — 12 files mapped, 5 dependencies, 3 tests found
2

Bước 2: Diagnose (BẮT BUỘC — không bao giờ skip)

Phân tích root cause có hệ thống. KHÔNG đoán.
  1. Ghi lại pre-fix state: error messages, failing test output, stack traces
  2. Kích hoạt ck:debug skill (systematic debugging + root cause tracing)
  3. Kích hoạt ck:sequential-thinking — hình thành giả thuyết qua lý luận
  4. Spawn Explore agents song song test từng giả thuyết
  5. Nếu 2+ giả thuyết sai → tự động kích hoạt ck:problem-solving
  6. Tạo diagnosis report: confirmed root cause, evidence chain
Output: Step 2: Diagnosed — Root cause: missing Site relation in Prisma include, Evidence: stack trace line 42
3

Bước 3: Complexity Assessment

Phân loại độ phức tạp trước khi chọn workflow:
LevelDấu hiệuWorkflow
Simple1 file, lỗi rõ ràng, type/lintQuick
ModerateNhiều file, root cause không rõStandard
ComplexSystem-wide, ảnh hưởng architectureDeep
Parallel2+ issues độc lậpMulti-agent
4

Bước 4: Fix Implementation

Implement fix dựa trên diagnosis findings. Fix ROOT CAUSE, không fix triệu chứng. Minimal changes, follow patterns hiện có.
5

Bước 5: Verify + Prevent (BẮT BUỘC)

  1. Verify: Chạy ĐÚNG commands từ pre-fix state. So sánh output.
  2. Regression test: Thêm/update test cho issue vừa fix. Test PHẢI fail nếu bỏ fix.
  3. Prevention gate: Thêm defense-in-depth nếu applicable.
  4. Parallel verification: Typecheck + lint + build + test chạy song song.
Nếu verify fail → quay lại Bước 2. Sau 3 lần fail → question architecture, hỏi user.Output: Step 5: Verified — before: HTTP 500, after: HTTP 201, 2 tests added, 1 guard added
6

Bước 6: Finalize (BẮT BUỘC)

  1. Report summary: confidence score, root cause, changes, files, prevention
  2. docs-manager subagent cập nhật ./docs/
  3. Hỏi user commit qua git-manager subagent
  4. Viết journal entry
Hard Gate: KHÔNG được đề xuất hay implement fix trước khi hoàn thành Bước 1-2 (Scout + Diagnose). Fix triệu chứng là THẤT BẠI. Tìm root cause trước.

Ví dụ thực tế

/fix "API returns 500 when creating new order with empty address"

So sánh với chat trực tiếp

Tiêu chí/fixChat trực tiếp
Diagnosis6 bước có hệ thống, evidence-basedĐoán nguyên nhân, thử fix
Root causeBẮT BUỘC tìm root cause trướcThường fix triệu chứng
Regression testBẮT BUỘC thêm test cho bug đã fixCó thể bỏ qua
PreventionThêm guards (validation, type check)Chỉ fix bug hiện tại
VerifyChạy lại ĐÚNG commands, so sánh before/afterClaim “đã fix” mà không verify
EscalationSau 3 lần fail → dừng, hỏi userTiếp tục thử
DocumentationTự động cập nhật docsKhông cập nhật

Khi nào dùng / không dùng

DùngKhông dùng
Bug runtime (500 error, crash)Implement feature mới (dùng /cook)
Tests đang failLập kế hoạch (dùng /plan)
TypeScript errorsReview code (dùng /code-review)
CI/CD bị lỗiTạo dự án mới (dùng /bootstrap)
UI/CSS bị vỡThay đổi business logic lớn

8 Sub-commands chi tiết

/fix "mô tả" — Intelligent Routing (mặc định)

Tự động detect loại bug và route tới sub-command phù hợp:
Keywords trong mô tảRoute tới
type, typescript, tsc/fix:types
ui, ux, design, layout, css, responsive/fix:ui
github actions, pipeline, ci/cd, build failed/fix:ci
test, spec, jest, vitest, failing test/fix:test
logs, error logs, stack trace/fix:logs
2+ issues không liên quan/fix:parallel
complex, architecture, refactor, system-wide/fix:hard
Mặc định (bug nhỏ, 1 file)/fix:fast

/fix:fast — Fix nhanh

/fix:fast
Cho bug đơn giản, biết nguyên nhân. Scout tối thiểu → diagnose → fix → review.

/fix:hard — Fix phức tạp

/fix:hard "race condition in concurrent order processing"
Dùng subagents plan + fix. Có research + brainstorm + deep analysis.

/fix:test — Fix failing tests

/fix:test
Chạy test suite → phân tích failures → tìm root cause → fix test code hoặc source code → chạy lại.

/fix:ci — Fix CI/CD

/fix:ci
Phân tích GitHub Actions logs → xác định bước fail → đề xuất và áp dụng fix.

/fix:types — Fix TypeScript errors

/fix:types
Chạy tsc --noEmit → tìm tất cả type errors → fix type definitions → đảm bảo strict mode pass.

/fix:ui — Fix UI issues

/fix:ui "form bị vỡ layout trên mobile"
Phân tích UI issues. Dùng ck:chrome-devtools screenshot + analyze. Fix layout, responsive, style.

/fix:logs — Phân tích logs

/fix:logs
Đọc application logs, server logs → tìm patterns lỗi → fix.

/fix:parallel — Fix song song

/fix:parallel "type errors + UI broken + test failures"
Nhiều fullstack-developer agents fix song song cho các issues độc lập.

Lưu ý & Best Practices

Sai lầm phổ biến:
  • Fix triệu chứng thay vì root cause → bug quay lại tuần sau
  • Không viết regression test → same bug tái phát khi refactor
  • Retry 3+ lần cùng approach → tốn token, vẫn không fix được
  • Dùng /fix chung thay vì sub-command chuyên biệt → chẩn đoán chậm
Tips từ team:
  • Luôn chẩn đoán trước: /scout/ck-debug → rồi mới /fix
  • Viết test reproduce bug TRƯỚC khi fix — đảm bảo fix đúng chỗ
  • Nếu 3 lần fail → dừng, dùng /brainstorm hoặc hỏi team
  • Dùng đúng sub-command: /fix:types cho TS errors, /fix:ci cho CI, /fix:ui cho layout
→ Xem thêm: Best Practices tổng hợp

Quy trình fix khuyên dùng

1

Chẩn đoán

/fix tự động chẩn đoán root cause trước khi sửa.
2

Fix

Áp dụng fix dựa trên root cause analysis.
3

Verify

Chạy lại tests để xác nhận fix không gây lỗi mới.
4

Regression

/qa-full:regression src/file-đã-sửa.ts