# Project Conventions (Override Skill Defaults)

> **MANDATORY:** These rules override ANY upstream skill default (including `writing-plans`, `generate-spec`, and all superpowers skills).
> Read this file before writing any output file during the Gate Workflow.

---

## DEV Workflow Output Paths (`AK-Docs/04.Coding/`)

Áp dụng cho taskType: `feature` · `bug-fix` · `refactor` · `investigation` · `documentation` · `gen-doc` · các taskType ML (xem `ml-conventions.md`).

> `gen-doc` (2-gate, ad-hoc document generation) và các ticket ML đều dùng **chung** bộ thư mục `AK-Docs/04.Coding/` bên dưới — không có section riêng. Chỉ khác số Gate được dùng (gen-doc chỉ dùng Gate 1–2, ML dùng đủ Gate 1–5).

### Standard tasks (feature, bug-fix, refactor, investigation, documentation, gen-doc, ML)

| Output | Path | Note |
|--------|------|------|
| Requirement doc | `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` | Gate 1 output |
| Implementation plan | `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` | Gate 2 output — **NOT** `docs/superpowers/plans/` |
| TDD Notes (test list + notes) | `AK-Docs/04.Coding/03.TDD-Notes/[functionId]/[ticketId].md` | Gate 3 output |
| Self-review / Summary | `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` | Gate 4 output |
| PR description | `AK-Docs/04.Coding/05.Pull-Requests/[functionId]/[ticketId].md` | Gate 5 output |
| Tracker | `AK-Docs/04.Coding/00.Overview/_Index.md` | Update mỗi gate: `F-ID \| Ticket \| Dev \| Gate \| PR` |

> **Override:** The `writing-plans` skill defaults to `docs/superpowers/plans/<filename>.md`.
> In this project, **always save plans to `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` instead.**

### functionId & ticketId

- `[functionId]` là mã định danh chức năng **do dự án quy định** (ví dụ `F-001_User-Login`, `AD06`, `UC-LOGIN`) — không ép format.
  - Được xác định BẮT BUỘC ở Gate 1 Pre-flight: từ `functionId`/`screenId` trong `.aiflow/context/current.json` → suy từ file UC Spec input (nội dung hoặc đường dẫn thư mục, ví dụ `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/`) rồi **hỏi DEV xác nhận** → cuối cùng mới hỏi DEV cung cấp trực tiếp.
  - KHÔNG ĐƯỢC ghi output khi chưa có functionId.
- `[ticketId]` lấy từ `taskId` trong `.aiflow/context/current.json` (ví dụ `TICKET-100`). Một feature có nhiều ticket → folder theo functionId, file theo ticketId.

### Legacy

- ❌ Đường dẫn cũ `plan/[ticket-id]/requirement.md`, `plan/[ticket-id]/plan.md`, `plan/[ticket-id]/summary.md`, `plan/[ticket-id]/output.md`, `plan/[ticket-id]/task-summary.md`, `plan/[ticket-id]/ml-problem.md`, `plan/[ticket-id]/experiment-plan.md`, `plan/[ticket-id]/eval-report.md` đã **DEPRECATED** cho MỌI taskType (kể cả `gen-doc` và ML) — không được ghi output mới vào `plan/`. Chỉ code/artifact thật sự thuộc source repo (hoặc cache thiết kế Figma — xem `read-study-requirement` skill) mới ở ngoài `AK-Docs`.

### gen-doc tasks (2-gate flow — NO `plan.md`, dùng chung thư mục Coding)

| Output | Path | Note |
|--------|------|------|
| Requirement doc | `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` | Gate 1 output — document outline |
| Document output | `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` | Gate 2 output — the generated document (or custom path/format — e.g. Excel — noted in the requirement doc; still record the path used in this file) |
| Task summary | `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId]-summary.md` | Auto-generated after Gate 2 |

> For gen-doc tasks: **do NOT create `plan.md`**. Gate 2 generates the output document directly.
> If the requirement specifies an Excel output or a custom path, generate it at that path, but still write a short pointer + summary into the Gate 2 output doc above so the tracker/AK-Docs history stays complete.
> `functionId` vẫn **BẮT BUỘC xác định ở Gate 1** theo đúng quy tắc "functionId & ticketId" ở trên — với gen-doc không suy ra được từ input thì hỏi trực tiếp người yêu cầu (ví dụ dùng ticketId rút gọn hoặc mã chủ đề báo cáo, ví dụ `AD-HOC` nếu task không gắn với chức năng cụ thể nào).

---

## ingest-data Workflow Output Paths (`AK-Docs/01.QnA/`)

Áp dụng cho taskType `ingest-data` (PM/BrSE/Comtor ingest communication — xem `.claude/skills/ingest-data/SKILL.md`). Khác với các taskType coding/gen-doc ở trên: **không** ghi vào `04.Coding/`, và **không** theo cấu trúc `[functionId]/[ticketId].md` — cả 3 file dưới đây là log dùng chung, phẳng, cho toàn dự án (append entry mới, không tạo file theo ticket):

| Log | Path | Ghi khi nào |
|---|---|---|
| QnA-Log | `AK-Docs/01.QnA/QnA-Log.md` | Trao đổi hỏi-đáp thông thường (file có sẵn — thêm cột `Nguồn` nếu chưa có) |
| Meetings-Log | `AK-Docs/01.QnA/Meetings-Log.md` | Tổng hợp 1 buổi họp — tạo file nếu chưa có |
| Confirmations-Log | `AK-Docs/01.QnA/Confirmations-Log.md` | Mốc khách CHỐT chính thức — tạo file nếu chưa có |

`functionId` cho Gate 2 (đặt tên branch `feature/[functionId]/[ticketId]`) vẫn theo đúng quy tắc "functionId & ticketId" ở trên — không suy ra được thì dùng `general` (tương tự gen-doc dùng `AD-HOC`).

> **Chưa đổi tên thư mục** `01.QnA/` thành `01.Communications/` như phương án đang chờ PM chốt trong `docs/internal/PM Workflow_v1.0.md` — giữ nguyên tên hiện có để không phá vỡ project đang chạy; đổi tên (nếu PM chốt) là 1 task migration riêng.

---

## Execution Handoff Message

When `writing-plans` skill says to announce the saved path, use the **actual path**:

```
Plan complete and saved to `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md`. Two execution options: ...
```

Do NOT copy the hardcoded path from the skill template (`docs/superpowers/plans/`).

---

## Checklist Before Writing Any File

Before saving any requirement, plan, TDD-notes, review, or PR file, verify:

- [ ] `functionId` đã được xác định/xác nhận ở Gate 1 Pre-flight
- [ ] `[ticketId]` is read from `.aiflow/context/current.json`
- [ ] Output path follows the table above — NOT the skill's default path, NOT the legacy `plan/` folder
- [ ] Directory `AK-Docs/04.Coding/<section>/[functionId]/` exists or will be created
- [ ] Tracker `AK-Docs/04.Coding/00.Overview/_Index.md` được cập nhật sau khi gate hoàn thành
- [ ] Announced path in the handoff message matches the actual saved path

---

## Other Conventions

- **Code style:** `custom/rules/code-style.md`
- **Naming:** `custom/rules/naming.md`
- **Folder structure reference:** `docs/common/Coding-Structure.md` · `docs/common/Project-Structure.md`