Scenario xử lý thay đổi cho BA team

Tài liệu này dành cho BA Lead và BA Member khi dự án đang chạy theo module nhưng xuất hiện thay đổi giữa chừng. Mục tiêu là giúp người không quen GitHub biết chính xác phải làm gì, báo ai, sửa ở đâu, cập nhật review packet hoặc mở PR thế nào, và khi nào được tiếp tục làm.

Từ BA-kit core commit dcb4b9f ngày 2026-04-28, các scenario dưới đây ưu tiên lớp BA-friendly trước:

1. Ghi nhận intent bằng ba-collab hoặc prompt tương đương theo runtime.
2. Cập nhật COLLAB-HOME.md, MODULE-HOME.md hoặc review packet nếu an toàn.
3. Route ba-impact trước nếu thay đổi chạm requirement, scope, actor, rule, navigation hoặc shared decision.
4. Cho phép agent thực hiện local sync an toàn sau plan ngắn nếu không có local changes/conflict.
5. Chỉ commit, push, tạo PR, request reviewer hoặc merge PR sau khi user approve rõ action plan.

Nguyên tắc chung:

• không sửa trực tiếp trên main
• không sửa core artifact trong PR module nếu chưa được giao
• thay đổi chạm scope, actor, rule, menu, navigation hoặc shared UX phải báo BA Lead
• core thay đổi trước, module cập nhật sau
• mỗi thay đổi lớn nên có review packet riêng; nếu dùng GitHub thì nên có một PR riêng để dễ review và rollback
• GitHub là lớp handoff/transport, không phải workflow đầu tiên cho BA non-tech
• Local Git sync là implementation detail của agent nếu workspace có quyền Git
• Nếu có local changes chưa commit, agent phải dừng hoặc hỏi cách xử lý; không tự stash/overwrite
• Nếu merge conflict chạm requirement docs, agent phải dừng và báo file/section cần Lead BA quyết định

Cách gọi theo runtime

Claude Code:

/ba-collab Tôi phát hiện CR trong module reporting: Export CSV phải ghi audit log.
/ba-start impact --slug warehouse-rfp

Codex:

$ba-collab Tôi phát hiện CR trong module reporting: Export CSV phải ghi audit log.
$ba-start impact --slug warehouse-rfp

Hoặc:

Use AGENTS.md and the ba-collab workflow.
Tôi phát hiện CR trong module reporting: Export CSV phải ghi audit log.
Do not commit, push, or create PR without explicit approval.

Antigravity:

Đọc BA-kit collaboration workflow và chạy intent:
Tôi phát hiện CR trong module reporting: Export CSV phải ghi audit log.

Nếu đây là requirement change, route impact trước.
Không commit, push, tạo PR hoặc merge PR nếu tôi chưa approve rõ.

Bảng phân loại nhanh

Scenario 1. Có Change Request từ stakeholder/client

Ví dụ:

• client đổi rule tính phí
• thêm actor mới
• thêm yêu cầu audit log
• thay đổi màn hình approval
• bỏ một feature đã chốt

BA Member phải làm gì

1. Dừng sửa artifact liên quan nếu đang làm dở.
2. Không tự sửa backbone, plan, DESIGN.md hoặc module artifact theo suy đoán.
3. Ghi lại CR bằng ngôn ngữ thật rõ:
   • ai yêu cầu
   • yêu cầu thay đổi là gì
   • module nào có vẻ bị ảnh hưởng
   • có deadline hoặc lý do business không
4. Comment vào PR đang mở hoặc nhắn BA Lead trong kênh team.
5. Nếu đang có PR module, đổi PR thành Draft nếu thay đổi có thể làm sai hướng.
6. Chờ BA Lead xác nhận impact và hướng rerun.
7. Nếu đang dùng BA-kit collaboration flow, yêu cầu agent cập nhật MODULE-HOME.md hoặc review packet thành blocked / changes-requested thay vì tự sửa artifact.

Mẫu message gửi Lead:

CR mới:
- Source: stakeholder A trong buổi review ngày 2026-04-24
- Nội dung: Export CSV phải ghi audit log và chỉ user có permission mới được export
- Em nghĩ ảnh hưởng: reporting module, user roles, SRS screen behavior
- PR hiện tại: ba/warehouse-rfp/reporting đang mở
- Em sẽ pause phần export cho đến khi anh/chị confirm impact

Runtime prompts tương đương:

/ba-collab Tôi phát hiện CR trong module reporting: Export CSV phải ghi audit log và chỉ user có permission mới được export. Pause module và gửi Lead BA review.

$ba-collab Tôi phát hiện CR trong module reporting: Export CSV phải ghi audit log và chỉ user có permission mới được export. Pause module và gửi Lead BA review.

Đọc BA-kit collaboration workflow và chạy intent: Tôi phát hiện CR trong module reporting, cần pause module và gửi Lead BA review. Nếu đây là requirement change, route impact trước.

BA Lead phải làm gì

1. Xác nhận CR có phải requirement change thật hay chỉ là wording/comment nhỏ.
2. Nếu là requirement change, chạy hoặc yêu cầu agent chạy impact.
3. Xác định layer bị ảnh hưởng:
   • 01_intake nếu scope/business goal thay đổi
   • 02_backbone nếu actor, rule, module boundary hoặc source of truth thay đổi
   • 03_modules/{module} nếu chỉ ảnh hưởng một module
   • designs/{slug}/DESIGN.md nếu đổi shared UI/UX direction
4. Ghi kết luận impact vào comment hoặc issue/note rõ ràng.
5. Nếu đổi core, tạo branch/PR core riêng.
6. Merge core PR vào main trước.
7. Thông báo member nào phải đồng bộ module với main.
8. Chỉ sau khi member đồng bộ module với main mới cho rerun module artifact.
9. Cập nhật COLLAB-HOME.md để các module affected có blocker hoặc next action rõ ràng.

GitHub step-by-step cho Lead

Chỉ làm bước này sau khi action plan được approve rõ. Nếu chưa cần GitHub, dừng ở impact result và review packet local.

1. Tạo branch mới từ main, ví dụ lead/warehouse-rfp-cr-audit-export.
2. Cập nhật đúng file core hoặc module theo kết quả impact.
3. Commit với message rõ, ví dụ docs(core): apply audit export change request.
4. Mở PR vào main.
5. Trong PR description, ghi:
   • CR source
   • affected artifacts
   • module nào cần rerun sau merge
6. Review hoặc nhờ peer review.
7. Merge PR.
8. Comment thông báo cho member: “Core CR đã merge, vui lòng đồng bộ module với main trước khi làm tiếp.”

Đồng bộ module sau khi core CR đã merge

Nếu team dùng ba-collab, trước khi đồng bộ hãy xem COLLAB-HOME.md hoặc MODULE-HOME.md để biết module của mình đang blocked, changes-requested hay được phép tiếp tục.

BA Member không cần tự chạy Git nếu agent có quyền. Nói bằng NLP:

Đồng bộ module reporting với main trước khi tôi làm tiếp.

Agent nên hiểu nội bộ:

check current branch
check uncommitted changes
fetch/pull main
switch to ba/warehouse-rfp/reporting
merge/rebase main theo policy
stop nếu có conflict

Agent phải show plan ngắn trước khi chạy:

Tôi sẽ:
1. Kiểm tra module reporting có thay đổi local không.
2. Cập nhật main từ origin.
3. Merge main vào branch module reporting.
4. Nếu có conflict, tôi sẽ dừng và liệt kê phần BA cần quyết định.

Không commit/push trong bước này.

Nếu dùng GitHub web và không quen xử lý branch:

1. Báo Lead rằng bạn cần đồng bộ branch/module theo main.
2. Không tự bấm các nút merge/update nếu GitHub báo conflict.
3. Nếu GitHub có nút Update branch và không báo conflict, có thể nhờ Lead xác nhận rồi bấm.
4. Sau khi branch đã cập nhật, sửa tiếp artifact module theo hướng dẫn mới.
5. Commit vào cùng branch module đang mở PR chỉ khi đã sẵn sàng ghi audit trail.
6. Quay lại PR và comment: “Đã cập nhật theo CR và rerun phần affected.”

Scenario 2. BA Member thấy menu hoặc UI/UX cần chỉnh

Ví dụ:

• member thấy menu hiện tại không hợp lý cho module mình
• screen cần thêm tab hoặc đổi label navigation
• action nên chuyển từ button sang menu item
• user flow cần thêm step để UX rõ hơn

Vấn đề: menu/navigation/shared UX thường là system-level. Nếu mỗi module tự sửa, toàn bộ SRS và wireframe handoff sẽ lệch nhau.

BA Member phải làm gì

1. Không sửa trực tiếp DESIGN.md, backbone hoặc shared navigation trong PR module.
2. Ghi proposal ngắn, gồm:
   • vấn đề đang thấy
   • màn hình hoặc use case liên quan
   • đề xuất đổi gì
   • lý do business/UX
   • module nào có thể bị ảnh hưởng
3. Nếu đang làm PR module, thêm proposal vào PR comment hoặc mở Draft PR nếu cần minh họa.
4. Gắn rõ đây là proposal, không phải change đã được approved.
5. Chờ BA Lead quyết định.
6. Nếu dùng ba-collab, gửi proposal như review packet local hoặc mark module blocked nếu đang phụ thuộc quyết định shared.

Mẫu proposal:

UI/UX proposal:
- Module: reporting
- Screen: SCR-RPT-03 Export History
- Vấn đề: Export History đang nằm dưới Settings nhưng user dùng hằng ngày, khó tìm
- Đề xuất: chuyển vào menu Reporting > Export History
- Ảnh hưởng có thể có: shared navigation, DESIGN.md, reporting SRS, wireframe-input
- Em chưa sửa navigation trong PR, chờ Lead confirm

BA Lead phải làm gì

1. Kiểm tra proposal có phải module-local hay shared navigation.
2. Nếu module-local, cho member sửa trong module PR và ghi rõ scope.
3. Nếu shared, Lead xử lý như core/design change:
   • cập nhật DESIGN.md
   • cập nhật backbone nếu navigation gắn với portal ownership hoặc actor flow
   • xác định module nào bị ảnh hưởng
4. Mở PR core/design riêng nếu cần.
5. Merge PR core/design trước.
6. Yêu cầu các member affected đồng bộ module với main và update artifact module sau.
7. Cập nhật COLLAB-HOME.md để module affected biết next action.

Khi nào member được tự sửa UI/UX trong module

Member có thể tự sửa trong PR module nếu thỏa tất cả điều kiện:

• chỉ đổi mô tả screen của module mình
• không đổi menu global
• không đổi actor/portal ownership
• không đổi shared component rule
• không khiến module khác phải sửa theo

Nếu không chắc, coi như shared change và hỏi Lead.

Scenario 3. BA Lead thay đổi core thì BA Member phải làm gì

Ví dụ core thay đổi:

• backbone.md đổi actor map
• plan.md đổi module boundary
• DESIGN.md đổi navigation schema
• project memory thêm approved decision mới
• global business rule được sửa

BA Lead phải làm gì trước

1. Cập nhật hoặc tạo review packet/core note cho thay đổi core.
2. Nếu dùng GitHub, mở PR core riêng sau approval.
3. Ghi rõ trong PR hoặc review packet:
   • file core nào đổi
   • lý do đổi
   • module nào bị ảnh hưởng
   • member nào cần update branch
4. Merge PR core vào main nếu team dùng GitHub.
5. Thông báo team bằng message ngắn, có checklist rõ.
6. Update COLLAB-HOME.md với affected modules và next action.

Mẫu thông báo:

Core update đã merge vào main:
- PR: #12
- Thay đổi: DESIGN.md đổi navigation schema cho Portal Admin
- Affected modules: auth-flow, reporting
- Member cần làm:
  1. pause work hiện tại
  2. yêu cầu agent đồng bộ module với main
  3. đọc lại DESIGN.md
  4. rerun/check wireframe-input và SRS screen sections
  5. comment lại PR module khi đã xử lý

BA Member phải làm gì sau thông báo

1. Dừng sửa tiếp cho đến khi biết branch của mình đã cập nhật.
2. Đọc thông báo của Lead để biết mình có bị ảnh hưởng không.
3. Nếu không bị ảnh hưởng, comment xác nhận “Module X not affected” nếu Lead yêu cầu.
4. Nếu bị ảnh hưởng, yêu cầu agent đồng bộ module với main.
5. Đọc lại file core bị đổi.
6. Kiểm tra artifact module của mình:
   • FRD có rule cũ không
   • stories có acceptance criteria cũ không
   • SRS có screen behavior/menu cũ không
   • wireframe-input có constraint cũ không
7. Sửa hoặc rerun đúng phần affected.
8. Commit vào branch module hiện tại.
9. Comment trong PR module:
   • đã sync core PR nào
   • đã sửa artifact nào
   • còn open question nào không
10. Nếu dùng collaboration dashboard, cập nhật MODULE-HOME.md hoặc review packet về trạng thái mới.

Nếu branch member bị conflict

1. Không tự xử conflict nếu không quen Git.
2. Yêu cầu agent giải thích conflict bằng ngôn ngữ BA và không sửa file.
3. Gửi danh sách file/section conflict cho BA Lead hoặc người hỗ trợ kỹ thuật.
4. Không copy paste file từ main đè vào branch nếu chưa hiểu, vì có thể mất phần đang làm.

Scenario 4. Member phát hiện core thiếu nhưng không chắc có phải CR

Ví dụ:

• backbone chưa có actor mà module đang cần
• plan chưa ghi rõ module boundary
• DESIGN.md chưa nói active menu state
• rule trong SRS cần nhưng backbone không có

Cách xử lý

1. Không tự bổ sung core trong module PR.
2. Tạo một comment trong PR, gửi note cho Lead, hoặc tạo review packet local bằng ba-collab.
3. Nêu rõ “đây là gap phát hiện khi làm module”, không gọi là CR nếu chưa chắc.
4. Lead quyết định:
   • nếu là gap nhỏ, cho member ghi assumption trong module artifact
   • nếu là core gap, Lead cập nhật core trước
   • nếu là requirement change, chạy impact
5. Member chỉ tiếp tục sau khi có hướng rõ.

Mẫu note:

Core gap:
- Khi làm module payment, em cần biết Refund Approver có phải actor riêng không
- Backbone hiện chỉ có Finance Admin
- Nếu Refund Approver là actor riêng thì ảnh hưởng UC-PAY-04 và approval screen
- Nhờ Lead confirm trước khi em viết tiếp SRS

Scenario 5. Hai module mâu thuẫn nhau

Ví dụ:

• module A gọi actor là Approver, module B gọi là Supervisor
• module A cho phép export CSV, module B nói export bị cấm
• module A dùng menu Reports, module B dùng Analytics cho cùng một khu vực

Member phải làm gì

1. Không tự sửa module của người khác.
2. Ghi rõ mâu thuẫn bằng 2 đường dẫn file cụ thể.
3. Báo Lead và tag member liên quan nếu team có quy ước tag.
4. Dừng phần artifact phụ thuộc vào quyết định đó.

Lead phải làm gì

1. Xác định mâu thuẫn nằm ở terminology, business rule, actor hay navigation.
2. Chọn source of truth cần sửa:
   • terminology/rule/actor: thường là backbone hoặc project memory hot shard
   • navigation/shared UX: thường là DESIGN.md
   • module-local detail: module artifact
3. Mở PR core nếu mâu thuẫn là shared.
4. Merge core PR.
5. Yêu cầu từng member affected sync và sửa module artifact.
6. Cập nhật COLLAB-HOME.md để các module liên quan có trạng thái blocked, changes-requested hoặc next action rõ.

Scenario 6. Member sửa nhầm file ngoài module

Ví dụ PR của auth-flow lại có thay đổi trong payment.

Member phải làm gì

1. Không merge PR.
2. Comment báo Lead: “PR đang lẫn file ngoài scope.”
3. Nếu sửa qua GitHub web, quay lại đúng file ngoài scope và revert bằng cách khôi phục nội dung cũ nếu Lead hướng dẫn.
4. Nếu dùng agent, yêu cầu agent tách lại thay đổi để PR chỉ còn đúng module; nếu có local changes chưa commit, agent phải hỏi trước khi stash/overwrite.
5. Sau khi cleanup, kiểm tra lại tab Files changed.
6. Nếu dùng ba-collab, mark review là conflict hoặc changes-requested cho đến khi scope sạch.

Lead phải kiểm tra gì

1. Tab Files changed chỉ còn đúng thư mục module.
2. Không có 02_backbone, designs/, module khác hoặc summary file bị chạm nhầm.
3. Nếu đã lỡ merge, mở hotfix PR để revert phần ngoài scope.

Scenario 7. PR bị conflict

Conflict nghĩa là GitHub không biết tự ghép thay đổi từ branch của bạn với main.

Trong BA-kit collaboration flow, conflict cũng nên được phản ánh ở COLLAB-HOME.md hoặc review packet với review status conflict, để BA non-tech biết đây là blocker chứ không phải lỗi nội dung nghiệp vụ.

BA Member không quen Git nên làm gì

1. Dừng lại, không bấm merge.
2. Không tự copy toàn bộ file từ nơi này qua nơi khác.
3. Gửi link PR cho Lead hoặc người hỗ trợ kỹ thuật.
4. Nêu rõ bạn đang muốn giữ phần nào trong module.
5. Chờ người hỗ trợ xử lý conflict hoặc hướng dẫn từng bước.

Lead/người hỗ trợ nên làm gì

1. Cập nhật branch member theo main sau khi kiểm tra local changes.
2. Giữ lại phần module work hợp lệ.
3. Loại bỏ phần file ngoài scope nếu có.
4. Nếu conflict là nghiệp vụ, dừng và hỏi Lead BA/owner trước khi sửa.
5. Chỉ push lại lên branch PR sau approval rõ.
6. Yêu cầu member kiểm tra nội dung sau conflict trước khi tiếp tục review.

Scenario 8. Sau khi merge mới phát hiện lỗi

Ví dụ:

• typo quan trọng
• acceptance criteria sai
• screen ID bị trùng
• module bị merge thiếu section
• link artifact sai

Cách xử lý

1. Không sửa trực tiếp trên main.
2. Báo Lead và ghi rõ lỗi nằm ở file/section nào.
3. Lead quyết định đây là hotfix nhỏ hay CR.
4. Nếu là hotfix nhỏ, tạo branch hotfix từ main.
5. Sửa đúng lỗi, không mở rộng scope.
6. Mở PR hotfix vào main.
7. Merge sau review nhanh.
8. Nếu lỗi ảnh hưởng requirement/source of truth, xử lý như Scenario 1.

Tên branch gợi ý:

fix/warehouse-rfp-reporting-screen-id
fix/warehouse-rfp-typo-srs

Scenario 9. Member muốn tiếp tục làm khi PR cũ chưa merge

Ví dụ member đã mở PR auth-flow, nhưng muốn bắt đầu payment.

Cách xử lý an toàn

1. Không làm module mới trên branch PR cũ.
2. Hỏi Lead xem có được bắt đầu module mới chưa.
3. Nếu được, nhận module mới qua ba-collab để cập nhật ownership/dashboard.
4. Nếu dùng GitHub, cập nhật main mới nhất.
5. Tạo branch mới từ main.
6. Làm module mới trên branch mới.
7. Giữ review packet/PR cũ và review packet/PR mới tách biệt.

Không nên dùng một branch cho nhiều module vì PR sẽ khó review và khó rollback.

Scenario 10. Review comment yêu cầu sửa nhưng member không hiểu

Member phải làm gì

1. Không đoán ý reviewer.
2. Reply ngay dưới comment và hỏi lại bằng câu cụ thể.
3. Nếu cần, đề xuất 1-2 cách hiểu để Lead chọn.
4. Chỉ sửa sau khi hiểu đúng yêu cầu.

Mẫu reply:

Em chưa chắc ý comment này là:
A. đổi acceptance criteria của story hiện tại
hay
B. thêm alternate flow trong SRS
Nhờ anh/chị confirm hướng đúng để em sửa đúng phạm vi.

Lead nên làm gì

1. Trả lời bằng action cụ thể.
2. Nếu comment chạm core scope, chuyển sang Scenario 1 hoặc 3.
3. Nếu chỉ là wording, nói rõ “wording-only, sửa trong PR hiện tại”.

Checklist nhanh cho BA Member

Trước khi sửa:

• tôi biết mình đang làm qua ba-collab local review hay qua GitHub PR
• nếu dùng GitHub, tôi đang ở branch riêng, không phải main
• tôi biết module mình sở hữu
• tôi đã đọc core mới nhất
• tôi biết thay đổi này là module-local hay shared/core
• nếu cần đồng bộ với main, tôi nói intent bằng NLP cho agent thay vì tự chạy lệnh Git khi không chắc

Khi phát hiện thay đổi:

• nếu chạm core, báo Lead
• nếu chạm menu/navigation/shared UX, báo Lead
• nếu là CR từ stakeholder, pause và báo Lead
• nếu không chắc, hỏi trước khi sửa

Trước khi gửi review packet hoặc mở/update PR:

• artifact hoặc tab Files changed chỉ có file đúng scope
• review packet hoặc PR description ghi assumption/open question
• nếu có CR/core update, review packet hoặc PR comment ghi đã sync từ PR nào
• nếu yêu cầu GitHub side effect, action plan đã được user approve rõ

Checklist nhanh cho BA Lead

Khi có thay đổi:

• phân loại change: wording, module-local, shared UI/UX, core requirement, CR
• nếu có impact thật, chạy impact trước
• core PR merge trước module PR
• cập nhật COLLAB-HOME.md / review packet để BA Member thấy blocker và next action
• thông báo rõ module affected
• yêu cầu member đồng bộ module với main sau khi core merge
• không cho merge PR module nếu còn mâu thuẫn với core mới