cowork-local/agent/workflow/intake_to_fix.md

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

0. Lane theo tier — đọc trước

Pipeline dưới đây là lane FULL (T3), không phải mặc định. 0_fix_dispatcher chấm tier trước và cắt bớt bước:

Tier	Lane	Bước thực chạy	Gọi agent
T0	DIRECT	hub sửa → 4 cổng máy (roles/0_fix_dispatcher.md §4.1)	0
T1	SOLO	hub triage inline → 5 → hub review bằng checklist/ui_review.md	1
T2	PAIR	hub triage inline → 2/3/4 → 5 → 6	3
T3	FULL	1 → 2/3/4 → 5 → 6	4–5
T3-SEC	FULL-SEC	7 → (Cowork Team) → 5 → 6	3 + chờ người

Bỏ bước nào cũng phải nêu rõ trong dispatch_plan cổng nào thay thế. Bước 6 chỉ được bỏ ở T0 và T1.

1. Pipeline (lane FULL)

  Người dùng báo lỗi (chat / issue / miệng)
              │
              ▼
  ┌───────────────────────────┐
  │ 0. fix-dispatcher   HUB   │  → dispatch_plan.md
  │    Router                 │     + tách N defect_id + tier + lane
  └───────────┬───────────────┘
              │ T0 → hub tự sửa, KHÔNG đi tiếp
              │ T1 → nhảy thẳng xuống bước 5
              │ T2 → nhảy thẳng xuống bước 2/3/4
              │ T3 → đi tiếp bước 1
              ▼
  ┌───────────────────────────┐
  │ 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
0. dispatcher	✅	✅ chỉ ở T0	✅ (grep, gate)	tier + lane + tách defect
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.

Ngoại lệ duy nhất là hub ở T0, và nó bị bó rất chặt để đổi lại: danh sách đóng 6 loại thay đổi, 9 disqualifier, trần ≤ 2 file / ≤ 10 dòng, và 4 cổng máy bắt buộc dán output thật. Vượt bất kỳ ràng buộc nào → git checkout -- rồi chấm lại T2. Hub không được sửa file ở T1/T2/T3 — ở đó nó chỉ điều phối và (ở T1) review, vì reviewer không được là người viết patch.

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
0 → bất kỳ	Mỗi defect_id có đúng 1 tier + 1 lane, tier ≠ T0 dẫn được về một dòng cụ thể của Bước 3, đã xét override bảo mật trước
0 → tự sửa (T0)	Trúng danh sách đóng, 0 disqualifier, Gate S + blast radius đã đo bằng lệnh
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).
• Tier +1 mỗi lần FAIL. Chạy lại ở nguyên tier cũ là lỗi điều phối: hai lần thất bại ở cùng độ sâu gần như luôn có nghĩa là hồ sơ lỗi sai từ đầu.
• Tier chỉ đi lên. Không có đường hạ tier giữa dòng, kể cả khi diff hoá ra nhỏ.
• 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ệ

Đây là các đường tắt hub được phép chọn ở Bước 3. Chúng thay thế phần "đường tắt" của bộ v1.2 — trước đây tự phát, giờ có tier và có cổng bù.

Tình huống	Tier	Đường tắt
Nới một số đo hiển thị (px, margin, spacing)	T0	hub sửa, 0 agent
Sai chính tả / sai dấu một chuỗi đã có key	T0	hub sửa, đủ 3 ngôn ngữ, vẫn phải có test
Đổi token màu có sẵn sang token có sẵn	T0	hub sửa, 0 agent
Thiếu key i18n, UI hiện ra a.b_c, đã biết file	T1	5 → hub review
Nguyên nhân gốc đã có file:line từ người báo (dev)	T1	5 → hub review
Chạm QSS/token dùng chung, phải kiểm 2 theme	T2	4 (hoặc 2) → 5 → 6
Lỗi do chính bản vá vừa merge	T3	đủ pipeline — regression nghĩa là nguyên nhân gốc lần trước sai
Dev báo thẳng một lỗ hổng	T3-SEC	vào thẳng 7, bỏ bước 1

Bước 6 chỉ được bỏ ở T0 và T1. Ở T0 nó được thay bằng 4 cổng máy; ở T1 nó được thay bằng hub review với checklist/ui_review.md (hợp lệ vì hub không viết patch ở T1). Ở T2/T3/T3-SEC không có đường tắt nào bỏ qua bước 6.

6. Chạy bằng Claude Code

mkdir -p .claude/agents .claude/commands
cp agent/roles/[1-7]_*.md .claude/agents/
cp agent/commands/fix.md  .claude/commands/

.claude/ nằm trong .gitignore (dòng 109) nên phải cài lại trên mỗi clone — agent/ là bản gốc. 0_fix_dispatcher.md không copy sang agents/: hub chạy ở session chính vì subagent không gọi được subagent. Điểm vào:

> /fix màn Folder kéo to ra thì mất cây thư mục bên trái

Hub in dispatch_plan rồi tự chạy lane. Muốn chạy tay lane FULL:

> 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

Các bước trong một defect_id chạy tuần tự — mỗi bước phụ thuộc output của bước trước. Các defect_id độc lập thì chạy song song được, gọi trong cùng một message.