Dev Journal

📝 Dev Journal — Ghi nhật ký mọi thay đổi

// turbo-all

Workflow này BẮT BUỘC chạy SAU mỗi session có thay đổi code/config/token/script. File log lưu tại dev-journal/ trong project root.

Chain: file-change → /post-change → /dev-journal (bạn đang ở đây)

⚠️ Cơ chế lưu: DAILY FILE — Tất cả entries trong cùng 1 ngày được gom vào 1 file duy nhất YYYY-MM-DD.md. KHÔNG tạo file riêng cho từng thay đổi.

Khi nào PHẢI ghi

Ngoại lệ: Không cần ghi khi chỉ đọc/review mà không thay đổi gì.

Steps

1. Xác định change type

Phân loại thay đổi để chọn template phù hợp:

2. Ghi entry vào file ngày

File name: dev-journal/YYYY-MM-DD.md (lấy ngày hiện tại)

Quy tắc:

• File đã tồn tại → APPEND entry mới vào cuối file, ngăn cách bằng ---
• File chưa tồn tại → Tạo file mới với daily header + entry đầu tiên
• Mỗi entry có <a id="slug"></a> để deep-link

Daily header (chỉ khi tạo file mới):

## 📅 Dev Journal — DD/MM/YYYY

> **Entries**: 1 change logged this day

---

Khi append entry mới:

1. Cập nhật số Entries trong header (tăng lên 1)
2. Thêm --- separator
3. Thêm <a id="slug-mô-tả-ngắn"></a> anchor
4. Ghi nội dung entry theo template ở Step 3

Slug rules (cho anchor ID):

• Dùng kebab-case, max 5 words
• Mô tả what changed, không phải why

3. Ghi nội dung theo template

Dùng template bên dưới. Các section có đánh dấu [IF ...] là conditional — chỉ thêm khi applicable.

## <Emoji> <Tiêu đề thay đổi>
### Nhật ký phát triển · <DD/MM/YYYY>

> **Mục tiêu**: <1 câu mô tả mục tiêu>
> **Type**: <change type từ Step 1>

---

### Vấn đề / Bối cảnh
<Mô tả vấn đề trước khi fix, hoặc lý do thay đổi>
<Context: tại sao cần thay đổi — design rationale>

### Giải pháp / Thay đổi
<Chi tiết các thay đổi đã thực hiện>
<Dùng diff blocks cho thay đổi quan trọng>
<Dùng tree view cho structural changes>

### [IF có test results] Kết quả test

| Check | Kết quả |
|-------|---------|
| sync-tokens | ✅/❌ detail |
| build-docs | ✅/❌ detail |
| lint-css | ✅/❌ detail |
| verify-output | ✅/❌ detail |
| verify-output (drift) | ✅/❌ detail |
| audit-components | ✅/❌ detail |

### [IF type = ds-gap] Token Change Log
<!-- Format từ token-governance §7 -->
TOKEN CHANGE LOG:
- Action     : CREATE | MODIFY | DELETE
- File       : tokens/{tier}/{file}.tokens.json
- Token      : {full.token.path}
- Value      : "{ref.path}"
- Reason     : ds-architect GAP-{NNN} — [mô tả]
- Approved by: User

### Files changed
- `path/to/file1` — Mô tả ngắn
- `path/to/file2` — Mô tả ngắn

### [IF breaking change] ⚠️ Breaking Changes
<Mô tả breaking changes và migration steps>

### [IF có gì cần follow-up] Follow-up
- [ ] Task cần làm tiếp
- [ ] Known issue chưa fix

---

*Entry by: Antigravity AI · DD/MM/YYYY*

4. Quality checklist (tự verify trước khi save)

• Tiêu đề rõ ràng — đọc tiêu đề biết ngay changed what
• Bối cảnh có "tại sao" — không chỉ "what" mà cả "why"
• Diff blocks — cho mọi thay đổi code/token quan trọng
• Files changed đầy đủ — dùng relative path (không absolute)
• Test results — nếu chạy post-change, PHẢI ghi kết quả
• Không gộp thay đổi khác chủ đề — 1 entry = 1 focused topic
• Ngôn ngữ nhất quán — Tiếng Việt nếu conversation context là VN

Quy tắc

Sizing

Content

1. Relative paths — dùng design-system/tokens/... thay vì e:\Prisma\design-system\tokens\...
2. Diff blocks cho thay đổi quan trọng — giúp trace lại nhanh
3. Tree view cho structural changes — folder restructure, file renames
4. Table cho test results — scan nhanh pass/fail
5. Tiếng Việt nếu conversation context là VN, English nếu EN
6. Không ghi khi chỉ đọc — chỉ ghi khi có thay đổi thực tế

Cross-references

Khi entry liên quan đến workflow/skill khác, ghi rõ:

> **Related**: Skill `component-lifecycle` § Create Workflow · Skill `component-lifecycle` §3