cowork-local/docs/instruction/agent/output_contract.md

output_contract.md — Hợp đồng đầu ra

Trách nhiệm của file này: định nghĩa format, thứ tự section và tiêu chuẩn trình bày của Fix Report. Đây là hợp đồng — không được thêm, bớt hay đổi thứ tự section.

1. Quy định chung

Hạng mục	Quy định
Sản phẩm giao	Hai phần: (1) thay đổi đã áp dụng vào code, (2) Fix Report dưới đây
Định dạng report	Markdown thuần
Ngôn ngữ	Tiếng Việt cho phần diễn giải; giữ nguyên tiếng Anh cho tên file, hàm, class, widget, token
Trích dẫn vị trí code	Luôn viết dạng path/to/file.py:123 để click được
Heading	# cho tiêu đề report, ## cho section, ### cho sub-section
Code block	Có tag ngôn ngữ (python, bash, ```diff)
Section trống	Cấm. Không áp dụng thì ghi N/A - <lý do>
Độ dài	Ngắn gọn, ưu tiên bảng. Không dán lại nguyên file khi chỉ sửa vài dòng

2. Quy ước ID

Tiền tố	Dùng cho	Ví dụ
CH-xx	Một thay đổi (change) trong code	CH-01
EV-xx	Một bằng chứng kiểm chứng (evidence)	EV-01
RG-xx	Một điểm rủi ro hồi quy (regression)	RG-01
AS-xx	Assumption	AS-01
OQ-xx	Open Question	OQ-01
LM-xx	Limitation — giới hạn đã biết, không giải quyết được trong lần sửa này	LM-01

3. Cấu trúc Fix Report (bắt buộc, đúng thứ tự)

# Fix Report - <mô tả ngắn vấn đề>

## 0. Summary
## 1. Root Cause
## 2. Changes
## 3. Diff
## 4. Verification
## 5. Regression & Impact
## 6. Assumptions, Open Questions & Limitations

0. Summary

Bảng gồm: Mode (CODE_FIX / LAYOUT_FIX / MIXED), Triệu chứng, Hành vi mong đợi, Số file đã sửa, Trạng thái test (Pass / Fail / Chưa chạy + lý do).

Tiếp theo là 2-3 câu mô tả: đã sửa gì, ở đâu, vì sao. Người đọc chỉ đọc mục 0 phải hiểu được toàn cảnh.

1. Root Cause

• Nguyên nhân gốc: một phát biểu duy nhất, chỉ rõ file.py:line.
• Cơ chế gây lỗi: giải thích chuỗi nhân quả từ nguyên nhân tới triệu chứng.
• Vì sao code cũ như vậy: nếu tra được qua git blame / comment, nêu ra — giúp tránh sửa hỏng chủ ý ban đầu.
• Phương án đã xét và loại: bảng Phương án | Lý do không chọn (tối thiểu 1 dòng).

Cấm dùng cách diễn đạt phỏng đoán ở section này: "có lẽ do", "có thể vì", "chắc là". Chưa chắc thì không được sửa — xem process.md Step 2.

2. Changes

Bảng CH-ID | File:line | Loại (Logic/Layout/Theme/Test) | Thay đổi | Lý do.

• Mỗi file bị chạm phải có ít nhất một dòng.
• Cột Lý do phải nối được về nguyên nhân gốc ở section 1, hoặc về một AS-xx.
• File bị chạm mà không giải thích được lý do → phải loại khỏi diff, không phải viết lý do cho nó.

3. Diff

• Diff thật của thay đổi, dạng ```diff hoặc trích đoạn before/after.
• Chỉ đoạn liên quan kèm vài dòng ngữ cảnh. Không dán cả file.
• Với LAYOUT_FIX chạm theme/: nêu rõ đã sửa theme/qss.py (hình dạng, khoảng cách) hay theme/palettes.py (màu), và selector nào bị ảnh hưởng.

4. Verification

Bảng EV-ID | Cách kiểm | Kết quả.

Yêu cầu bắt buộc theo chế độ:

Chế độ	Bằng chứng tối thiểu
CODE_FIX	Lệnh test đã chạy + output nguyên văn; với sửa logic: test hồi quy fail trước / pass sau
LAYOUT_FIX	Đã kiểm ở 2 kích thước cửa sổ, cả theme sáng và tối, và với text dài
MIXED	Đủ cả hai nhóm trên

Ghi lại nguyên văn kết quả. Quy tắc tuyệt đối:

• Test fail → ghi Fail kèm output, không che đi.
• Chưa chạy được → ghi Chưa chạy - <lý do>, không ghi là pass.
• Không suy đoán kết quả kiểm chứng chưa từng thực hiện.

5. Regression & Impact

Bảng RG-ID | Nơi bị ảnh hưởng | Loại (Hàm/Widget/QSS selector/Theme token/Test) | Mức rủi ro | Đã kiểm chưa.

• Phải nêu mọi nơi khác đang dùng thứ vừa sửa (kết quả rà ở process.md Step 5.4).
• Không có nơi nào khác dùng → ghi rõ Không có nơi nào khác sử dụng kèm cách đã rà (ví dụ: đã grep tên hàm / tên selector trên toàn repo).

6. Assumptions, Open Questions & Limitations

• Bảng Assumption: AS-ID | Nội dung giả định | Căn cứ | Tác động nếu giả định sai.
• Bảng Open Question: OQ-ID | Câu hỏi | Người cần trả lời | Phương án đề xuất | Blocking (Yes/No).
• Bảng Limitation: LM-ID | Giới hạn | Nguyên nhân | Ảnh hưởng tới kết quả | Cần gì để vượt qua.
• Nơi ghi các việc cố ý không làm: code xấu phát hiện dọc đường, refactor nên làm sau, test còn thiếu. Ghi ở đây thay vì tự ý sửa trong cùng lần fix.

Phân biệt ba loại — dùng sai loại thì reviewer không biết phải làm gì với nó:

Loại	Khi nào dùng	Ai xử lý tiếp
AS-xx Assumption	Bạn đã chọn một cách hiểu hợp lý và đã sửa theo cách đó	Reviewer xác nhận hoặc bác bỏ giả định
OQ-xx Open Question	Bạn không được phép chọn — cần người khác quyết định (nhất là quyết định nghiệp vụ)	Người được nêu trong cột owner trả lời
LM-xx Limitation	Không ai cần quyết định gì, nhưng có giới hạn khách quan khiến kết quả chưa trọn vẹn: không tái hiện được trên môi trường hiện có, không viết được test vì thiếu fixture, chỉ sửa được một phần vì phần còn lại thuộc module bị khoá	Chấp nhận, hoặc mở task riêng

Quy tắc: giới hạn không giải quyết được thì phải ghi thành LM-xx, không được im lặng bỏ qua và không được trình bày kết quả như đã trọn vẹn.

4. Đề xuất commit (không tự chạy)

Cuối report, đề xuất commit message theo convention của repo — Conventional Commit, scope là optional:

fix(<scope>): <mô tả ngắn ở thể mệnh lệnh>

Prefix cho phép: feat: fix: test: docs: refactor: perf: chore:.

Chỉ đề xuất. Không tự git add, git commit, git push hay tạo pull request khi người dùng chưa yêu cầu. Nếu đang ở nhánh mặc định (main), nêu rõ rằng cần tạo nhánh riêng trước khi commit.

5. Khối Self-review Result

Đặt sau Fix Report, không lẫn vào trong:

### Self-review Result
| Nhóm | Pass/Tổng | Điểm |
|---|---|---|
| G1 Root cause | 4/4 | 25 |
| ... | ... | ... |
| **Tổng** | | **xx/100** |

Số vòng sửa: <n>
Mục đã chuyển thành Open Question: OQ-xx

6. Định dạng khi không thể tiến hành

Ba trường hợp không xuất Fix Report (xem input_contract.md §3 và process.md Step 2). Dùng đúng khối tương ứng, ngắn gọn, không kèm code sửa:

Thiếu input bắt buộc

## Missing Required Input
| # | Thông tin cần cung cấp | Vì sao cần |
|---|---|---|
| 1 | ... | ... |

Không tái hiện được lỗi

## Cannot Reproduce
- Repro đã thử: ...
- Kết quả quan sát: ...
- Cần thêm: ...

Không xác định được nguyên nhân gốc

## Root Cause Not Confirmed
| # | Nguyên nhân khả dĩ | Bằng chứng ủng hộ | Cách kiểm chứng đề xuất |
|---|---|---|---|
| 1 | ... | ... | ... |

Lý do chưa sửa: chưa phân biệt được các khả năng trên, sửa lúc này sẽ là sửa mò.