# Hướng dẫn sử dụng — `ba-lifecycle`

## Skill này làm gì

Trả lời bốn câu hỏi, không làm gì hơn:

1. Dự án này thuộc **loại nào** — và vì thế pipeline chạy ra sao?
2. Đang ở giai đoạn nào?
3. Cái gì đang chặn tôi đi tiếp?
4. Tôi nên chạy skill nào tiếp theo?

Nó **đọc** artifact chứ không viết artifact nghiệp vụ. Hai file duy nhất nó tạo/sửa:
`00-index/PROFILE_<PROJECT>.md` và `00-index/INDEX_<PROJECT>.md`.

## Profile — việc đầu tiên với mọi project mới

Lần đầu chạy, skill đề xuất ba trục và hỏi xác nhận:

```
PROFILE = PRODUCT × LIFECYCLE × RIGOR
```

| Trục | Quyết định | Chọn sai thì sao |
|---|---|---|
| **PRODUCT** `screen` · `api-service` · `data-pipeline` · `ml-model` · `batch-job` · `process-only` | GĐ3 viết cái gì | Skill đòi bạn điền bảng field cho một pipeline dữ liệu |
| **LIFECYCLE** `greenfield` · `brownfield` · `enhancement` | GĐ1/GĐ2 nặng ở đâu | Bỏ qua phân tích dữ liệu cũ trong dự án brownfield |
| **RIGOR** `light` · `standard` · `strict` | Gate chặt tới đâu, ai ký | POC bị đòi 3 chữ ký, hoặc hệ thống tài chính bỏ qua SoD |

Chi tiết: [`references/domain-profiles.md`](references/domain-profiles.md).
Chưa xác nhận profile ⇒ skill chấm gate theo mặc định `standard` và **nói rõ là đang dùng
mặc định**.

## Khi nào gọi

| Tình huống | Gọi |
|---|---|
| Mới nhận một module, chưa biết bắt đầu từ đâu | `/ba-lifecycle <PROJECT>` |
| Quay lại dự án sau vài tuần, quên đang làm dở gì | `/ba-lifecycle <PROJECT>` |
| Chuẩn bị họp gate, cần biết còn thiếu gì | `/ba-lifecycle <PROJECT>` |
| Sau khi chạy xong một skill giai đoạn, muốn đồng bộ INDEX | `/ba-lifecycle <PROJECT>` |
| Sếp hỏi "tiến độ tài liệu BA đến đâu rồi" | `/ba-lifecycle <PROJECT>` |

**Không** gọi khi bạn đã biết rõ mình cần viết tài liệu gì — gọi thẳng skill giai đoạn cho nhanh.

## Cú pháp

```
/ba-lifecycle <PROJECT> [--out <đường-dẫn>] [go]
```

| Tham số | Ý nghĩa |
|---|---|
| `<PROJECT>` | Tên dự án/module. Cũng chấp nhận mã US: `/ba-lifecycle US059` |
| `--out` | Thư mục gốc khác `ba-output/` |
| `go` | Bỏ bước dừng xác nhận input |

## Chuẩn bị gì trước khi gọi

Lần đầu với một dự án: **không cần gì cả**. Skill sẽ hỏi bạn tên project và nơi ghi output,
rồi tạo cấu trúc thư mục.

Dự án đã có tài liệu ở nơi khác (`.docs/output/`, Confluence export, thư mục Word cũ):
nói rõ đường dẫn khi gọi, để skill đọc chúng thay vì báo "chưa có gì".

```
/ba-lifecycle Settlement — tài liệu cũ nằm ở d:/Kakao/BA/berriz-platform-docs/.docs/output
```

## Bạn sẽ nhận được gì

Bốn phần, luôn theo thứ tự này:

**① Bảng pipeline** — 5 dòng, mỗi gate một dòng, cột "Thiếu gì" là phần đáng đọc nhất.

```
| Gate | Giai đoạn | Artifact              | Trạng thái | Thiếu gì                          |
|------|-----------|-----------------------|-----------|------------------------------------|
| G1   | Discovery | BRIEF v1.0, STK v1.0  | ✅        | —                                  |
| G2   | Analysis  | BACKLOG v0.4          | 🟠        | Chưa có BR, RBAC, IMPACT; PO chưa ký|
| G3   | Spec      | —                     | ☐         | Chưa bắt đầu                       |
```

**② Đang đứng ở đâu** — một câu.

**③ Việc tiếp theo** — tối đa 3 việc, mỗi việc kèm lệnh chạy sẵn để copy.

**④ Cảnh báo** — OQ quá hạn, tham chiếu gãy, artifact lệch version.

## Ví dụ hội thoại

```
Bạn:    /ba-lifecycle Settlement

Claude: [Bước 0] Tôi tìm thấy:
        | File                                    | Vai trò | Giai đoạn | Sửa lần cuối |
        | ba-output/Settlement/01-discovery/BRIEF_Settlement_v1.0.md | Project Brief | 1 | 2026-08-20 |
        | ba-output/Settlement/02-analysis/BACKLOG_Settlement_v0.4.md | Backlog | 2 | 2026-08-28 |

        Ngoài ra có d:/Kakao/BA/berriz-platform-docs/.docs/output/ chứa 12 file
        — đây là pipeline `ba:*` riêng của Berriz. Bạn muốn tôi đọc luôn hay bỏ qua?

        Output sẽ ghi vào ba-output/Settlement/. Xác nhận giúp tôi.

Bạn:    Đọc luôn cả .docs/output. Output giữ nguyên ba-output.

Claude: [bảng pipeline + 3 việc tiếp theo + cảnh báo]
```

## Lỗi thường gặp

**"Nó báo G1 chưa xong mà tôi họp duyệt rồi."**
Gate chấm theo dòng `Approved by` trong header artifact, không theo trí nhớ. Họp xong phải
điền tên người duyệt + ngày vào header. Chưa điền thì với skill là chưa duyệt — và đúng ra
là như vậy, vì sáu tháng sau không ai chứng minh được đã duyệt.

**"Nó bảo tôi thiếu IMPACT nhưng module này không tác động gì cả."**
Vẫn phải có file, nội dung ghi "không có tác động" kèm lý do và phạm vi đã rà. "Đã rà và
không thấy" khác hoàn toàn "chưa rà".

**"Tôi có nhiều module, chạy một lần được không?"**
Không. Mỗi lần một project, để bảng pipeline còn đọc được. Nhiều module thì chạy lần lượt.

**"Nó tự sửa file SRS của tôi."**
Không được phép, và SKILL.md cấm điều đó. Nếu xảy ra, báo lại — đó là bug của skill. Skill
này chỉ ghi `PROFILE` và `INDEX`.

**"Dự án tôi là POC, sao nó đòi đủ thứ?"**
Khai `RIGOR = light` trong profile. Nhưng bốn thứ không bao giờ bỏ ở bất kỳ mức nào: phát
biểu bài toán · ít nhất một `GOAL` có cách đo · `OQ` cho mọi chỗ chưa rõ · `DEC-nn` cho mọi
quyết định. POC hôm nay thành sản phẩm sáu tháng sau là chuyện thường.

**"POC được duyệt thành sản phẩm thật rồi."**
Nâng `RIGOR` lên `standard` và **chạy bù** G1–G3 theo checklist đầy đủ trước khi làm tiếp,
ghi `DEC-nn`. Skill sẽ chủ động cảnh báo điều này khi thấy project `light` đã có người dùng
thật ngoài nhóm làm.

## Liên quan

- Ba trục profile và cách chọn: `references/domain-profiles.md`
- Định nghĩa gate, tiêu chí pass theo từng mức `RIGOR`: `references/workflow.md`
- Artifact nào ở đâu, header bắt buộc: `references/artifact-map.md`
- Quy tắc viết tài liệu: `references/writing-rules.md`
- Kiểm tra coverage định lượng: skill `ba-traceability`