# Workflow — từ phản ánh của người dùng tới PR

## 1. Pipeline

```text
  Người dùng báo lỗi (chat / issue / miệng)
              │
              ▼
  ┌───────────────────────────┐
  │ 1. ui-bug-triage          │  → defect_record.md
  │    Planner                │     + category + severity + confidence
  └───────────┬───────────────┘
              │ route theo category  (security THẮNG mọi nhóm khác)
      ┌───────┬─┴──────┬──────────┬───────────┐
      ▼       ▼        ▼          ▼           ▼
  ┌────────┐┌────────┐┌──────────┐┌─────────┐ not-ui
  │ 2.     ││ 3.     ││ 4.       ││ 7.      │ → RETURN_TO_REPORTER
  │ visual ││ flow   ││ i18n-a11y││ security│   (mở issue type:bug thường)
  └────┬───┘└───┬────┘└────┬─────┘└────┬────┘
       └────────┼──────────┴───────────┘
                │   ⚠ role 7 có thể dừng ở đây:
                │   4 câu chính sách chưa có đáp án
                │   → RETURN_TO_REPORTER (needs-security-decision)
                ▼  fix_plan.md
  ┌───────────────────────────┐
  │ 5. fix-implementer        │  → patch + fix_report.md
  │    Executor (SỬA FILE)    │     + CASAN gate output
  └───────────┬───────────────┘
              ▼
  ┌───────────────────────────┐
  │ 6. regression-reviewer    │  → verdict + pr_body.md
  │    Reviewer               │
  └───────────┬───────────────┘
       FAIL ──┘ (quay lại 5, hoặc về 2/3/4 nếu sai nguyên nhân gốc)
       PASS ──▶ Cowork Team review → merge
```

## 2. Ai được làm gì

| Agent | Đọc | Sửa file | Chạy lệnh | Quyết định |
|---|---|---|---|---|
| 1. triage | ✅ | ❌ | ✅ (grep, tra manifest) | phân loại + route |
| 2/3/4. specialist | ✅ | ❌ | ✅ (đọc, kiểm LOC) | nguyên nhân gốc + phương án |
| 7. security | ✅ | ❌ | ✅ (đọc, `git log -S`) | lỗ hổng + migration; **không** quyết chính sách |
| 5. implementer | ✅ | ✅ | ✅ (git, pytest, gate) | cách hiện thực trong phạm vi plan |
| 6. reviewer | ✅ | ❌ | ✅ (git, pytest, gate) | PASS / FAIL |
| Cowork Team | — | — | — | **merge** |

Chỉ **một** agent được sửa file. Ranh giới này là thứ giữ cho pipeline review được.

## 3. Cổng chuyển bước

Không bước nào được đi tiếp nếu chưa đạt:

| Từ → Đến | Điều kiện |
|---|---|
| 1 → 2/3/4 | `confidence >= medium`, có ít nhất một `file:line`, đã redact |
| 2/3/4 → 5 | Đúng **một** nguyên nhân gốc, có cách kiểm chứng, không vượt 400 LOC (hoặc đã có kế hoạch tách) |
| 7 → 5 | Như trên, **cộng thêm**: có đường di trú cho cả 4 nhóm người dùng, và 4 câu chính sách đã có đáp án của Cowork Team |
| 5 → 6 | 5 cổng CASAN xanh, test regression đỏ-trước-xanh-sau |
| 6 → người | Verdict PASS/PASS_WITH_NOTES + `pr_body` |

`confidence: low` ở bất kỳ đâu → quay về bước 1. Không đoán tiếp.

## 4. Vòng lặp và giới hạn

- FAIL ở bước 6 → về bước 5 (lỗi hiện thực) hoặc về 2/3/4 (sai nguyên nhân gốc).
- Quá **2 vòng** mà vẫn FAIL → dừng, đưa người thật vào. Vòng thứ ba thường có nghĩa là
  `defect_record` sai từ đầu, không phải bản vá sai.

## 5. Đường tắt hợp lệ

| Tình huống | Đường tắt |
|---|---|
| Lỗi chính tả một chuỗi, đã biết chính xác key | 1 → 4 → 5 → 6, bỏ giai đoạn điều tra ở bước 4 |
| Thiếu key i18n, UI hiện ra `a.b_c` | 1 → 4 → 5 → 6 |
| Lỗi do chính bản vá vừa merge | về thẳng 5 nếu nguyên nhân gốc chưa đổi |
| Dev báo thẳng một lỗ hổng, không qua triệu chứng giao diện | vào thẳng 7, bỏ bước 1 |

Không có đường tắt nào bỏ qua bước **6**.

## 6. Chạy bằng Claude Code

```bash
mkdir -p .claude/agents && cp agent/roles/*.md .claude/agents/
```

Rồi lần lượt:

```text
> dùng ui-bug-triage cho phản ánh này: "màn Folder kéo to ra thì mất cây thư mục bên trái"
> dùng ui-visual-fixer với defect_record ở trên
> dùng fix-implementer với fix_plan ở trên
> dùng regression-reviewer với patch vừa rồi
```

Chạy tuần tự, không song song — mỗi bước phụ thuộc output của bước trước.