---
name: product-docs
description: >
  Write and maintain product documentation: PRD (Product Requirements Document),
  user guides, feature specs, release notes, and changelogs. CRITICAL: this skill
  enforces sync discipline — whenever a feature changes, ALL affected doc modules
  must be updated together. Trigger on: PRD, product requirements, feature spec,
  user guide, user manual, hướng dẫn sử dụng, tài liệu tính năng, mô tả chức năng,
  release notes, changelog, "viết tài liệu", "cập nhật docs", "thêm tính năng mới",
  "tính năng thay đổi", "feature changed", "update documentation", "write spec",
  "describe feature", "how does X work", "document this". Also trigger when code
  changes are made that affect user-facing behavior — proactively ask if docs need update.
---

# Product Docs

Viết và bảo trì tài liệu sản phẩm: PRD, User Guide, Feature Specs, Release Notes.

## Nguyên tắc cốt lõi

> **"Code thay đổi → Docs phải thay đổi cùng lúc, không phải sau."**

Mỗi khi tính năng được thêm, sửa, hoặc xóa — skill này đảm bảo tất cả module
tài liệu liên quan được identify và cập nhật đồng bộ.

## Khi nào dùng

- Viết PRD cho tính năng mới
- Tạo/cập nhật User Guide
- Viết Feature Spec chi tiết
- Tạo Release Notes / Changelog
- Review tài liệu hiện có khi code thay đổi
- "Tính năng X vừa thay đổi, cần update docs gì?"

## Khi KHÔNG dùng

- Tài liệu kỹ thuật nội bộ (API docs, architecture — dùng code-review skill)
- Commit messages (dùng git-workflow skill)

---

## Quy trình 3 pha

```
Phase 1: IDENTIFY  →  Phase 2: WRITE  →  Phase 3: SYNC CHECK
Xác định scope       Viết nội dung       Kiểm tra tất cả
và modules           theo template       modules đã đồng bộ
```

### Phase 1 — IDENTIFY trước khi viết

Trước khi bắt đầu viết bất kỳ tài liệu nào, trả lời:

```
1. Đây là tính năng MỚI hay THAY ĐỔI tính năng cũ?
   → Mới: cần tạo docs mới + cập nhật navigation/TOC
   → Thay đổi: cần tìm TẤT CẢ chỗ đã đề cập tính năng này

2. Tính năng này xuất hiện trong module nào?
   ☐ PRD / Feature Spec
   ☐ User Guide / Manual
   ☐ Onboarding / Tutorial
   ☐ FAQ / Troubleshooting
   ☐ Release Notes / Changelog
   ☐ README / Quick Start
   ☐ API Documentation (nếu có endpoint thay đổi)
   ☐ In-app tooltips / help text

3. Ai bị ảnh hưởng?
   → End users: cập nhật User Guide
   → Developers: cập nhật API docs / README
   → Admin: cập nhật Admin Guide
   → Tất cả: cập nhật Release Notes
```

### Phase 2 — WRITE theo template

Xem `templates/` folder cho từng loại tài liệu:
- `prd-template.md` — PRD đầy đủ
- `user-guide-template.md` — Hướng dẫn sử dụng
- `release-notes-template.md` — Release Notes / Changelog

### Phase 3 — SYNC CHECK (bắt buộc)

Sau khi viết xong, chạy checklist này:

```
Sync Checklist:
☐ PRD đã phản ánh trạng thái HIỆN TẠI (không phải kế hoạch cũ)?
☐ User Guide đã có screenshot/step mới nếu UI thay đổi?
☐ Release Notes đã ghi nhận thay đổi này?
☐ FAQ có câu hỏi nào cần cập nhật không?
☐ Onboarding flow còn đúng không?
☐ Version number / date đã cập nhật?
☐ Các cross-reference links còn hoạt động?
☐ Tính năng bị XÓA đã được ghi vào "Deprecated" section?
```

---

## Module 1 — PRD (Product Requirements Document)

### Cấu trúc chuẩn

```markdown
# [Tên Tính Năng] — PRD

**Version:** 1.x  |  **Cập nhật:** DD/MM/YYYY  |  **Author:** [Tên]
**Status:** 🟡 Draft / 🟢 Approved / 🔵 In Development / ✅ Shipped / ⚫ Deprecated

---

## 1. Tổng quan
[2-3 câu: tính năng là gì, giải quyết vấn đề gì, cho ai]

## 2. Vấn đề cần giải quyết (Problem Statement)
**Người dùng hiện tại gặp phải:**
- [Pain point 1]
- [Pain point 2]

**Hậu quả nếu không giải quyết:**
[Mô tả impact]

## 3. Mục tiêu (Goals)
**In scope:**
- [ ] [Goal 1 — đo lường được]
- [ ] [Goal 2]

**Out of scope:**
- [Những gì KHÔNG làm trong version này]

## 4. Người dùng (Users)
| Persona | Mô tả | Nhu cầu chính |
|---------|-------|---------------|
| [Tên] | [Mô tả] | [Nhu cầu] |

## 5. Yêu cầu chức năng (Functional Requirements)

### 5.1 [Tên nhóm chức năng]
**FR-01:** [Mô tả yêu cầu]
- Điều kiện: [Precondition]
- Hành vi: [Expected behavior]
- Ngoại lệ: [Edge cases]

**FR-02:** ...

## 6. Yêu cầu phi chức năng (Non-Functional Requirements)
- **Performance:** [Ví dụ: Load < 2s]
- **Security:** [Ví dụ: Chỉ user có role X mới truy cập được]
- **Accessibility:** [WCAG AA / ngôn ngữ hỗ trợ]
- **Mobile:** [Responsive / Native]

## 7. User Flow
[Mermaid diagram hoặc numbered steps]

## 8. UI/UX Notes
[Wireframe reference, design principles, key screens]

## 9. Tiêu chí hoàn thành (Acceptance Criteria)
- [ ] [AC-01: Khi X, hệ thống phải Y]
- [ ] [AC-02: ...]

## 10. Metrics đo lường thành công
| Metric | Baseline | Target | Đo bằng |
|--------|----------|--------|---------|

## 11. Dependencies
- [Tính năng/team khác cần phối hợp]

## 12. Changelog
| Version | Ngày | Thay đổi | Author |
|---------|------|---------|--------|
| 1.0 | DD/MM/YYYY | Initial draft | [Tên] |
```

### Nguyên tắc viết FR (Functional Requirements)

```
✓ Dùng "Hệ thống phải..." / "User có thể..." — không dùng "Nên" cho requirements cứng
✓ Mỗi FR có ID duy nhất (FR-01, FR-02...) để trace
✓ Đủ cụ thể để QA viết test case từ đó
✓ Tách biệt WHAT (cần gì) và HOW (làm thế nào)
✓ Include edge cases và error states

❌ "Hệ thống phải nhanh" → ✅ "Load time < 2s với 95th percentile"
❌ "User có thể filter" → ✅ "User có thể filter danh sách theo: ngày tạo, trạng thái, người tạo"
❌ "Xử lý lỗi tốt" → ✅ "Khi upload thất bại, hiển thị message 'Upload thất bại, thử lại' và giữ nguyên form"
```

---

## Module 2 — User Guide (Hướng dẫn sử dụng)

### Cấu trúc chuẩn

```markdown
# Hướng dẫn sử dụng: [Tên App/Tính Năng]

**Phiên bản:** x.x  |  **Cập nhật:** DD/MM/YYYY

---

## Bắt đầu nhanh (Quick Start)
[3-5 bước để người dùng mới dùng được ngay]

1. [Bước 1]
2. [Bước 2]
3. [Bước 3]

---

## [Tên Tính Năng 1]

### Mô tả
[1-2 câu: tính năng này làm gì, dùng khi nào]

### Cách sử dụng

**Bước 1:** [Mô tả hành động]
> 💡 **Mẹo:** [Tip hữu ích nếu có]

**Bước 2:** [Mô tả hành động]

**Bước 3:** [Mô tả hành động]

### Kết quả
[Mô tả user thấy gì sau khi hoàn thành]

### Lưu ý
> ⚠️ [Warning quan trọng nếu có]

---

## Câu hỏi thường gặp (FAQ)

**Q: [Câu hỏi phổ biến]?**
A: [Trả lời rõ ràng]

---

## Xử lý sự cố (Troubleshooting)

| Vấn đề | Nguyên nhân | Giải pháp |
|--------|-------------|-----------|
| [Lỗi/vấn đề] | [Lý do] | [Cách fix] |
```

### Nguyên tắc viết User Guide

```
✓ Viết cho người KHÔNG có kiến thức kỹ thuật
✓ Mỗi bước = 1 hành động cụ thể, không gộp nhiều việc
✓ Dùng "bạn" — không dùng "người dùng" hay "they"
✓ Screenshot/ảnh minh họa cho bước phức tạp
✓ Kết quả mỗi bước phải observable ("bạn sẽ thấy...")
✓ Warning box cho thao tác không thể hoàn tác

❌ "Điều hướng đến Settings và cấu hình các thông số"
✅ "1. Click icon ⚙️ góc trên phải
    2. Chọn 'Cài đặt tài khoản'
    3. Bạn sẽ thấy trang Cài đặt mở ra"
```

---

## Module 3 — Release Notes & Changelog

### Format chuẩn (Keep a Changelog)

```markdown
# Changelog

Mọi thay đổi quan trọng sẽ được ghi lại tại đây.
Format theo [Keep a Changelog](https://keepachangelog.com).

---

## [Unreleased]
### ✨ Thêm mới
- [Tính năng đang phát triển]

---

## [1.2.0] — 2025-05-15

### ✨ Thêm mới
- Tính năng X: [Mô tả ngắn gọn giá trị cho user]
- Tính năng Y: [...]

### 🔧 Cải thiện
- Tăng tốc độ load trang dashboard 40%
- Cải thiện UX form đăng ký: giảm từ 8 → 5 trường

### 🐛 Sửa lỗi
- Fixed: [Mô tả lỗi] — [Điều kiện gây ra lỗi]
- Fixed: Upload ảnh thất bại khi file > 5MB trên iOS Safari

### ⚠️ Breaking Changes
- API endpoint `/api/v1/users` đổi thành `/api/v2/users`
  → Migration: thay URL trong tất cả API calls

### 🗑️ Đã xóa / Deprecated
- Xóa tính năng [X] (đã deprecated từ v1.0)
- Deprecated: [Y] — sẽ xóa trong v2.0

---

## [1.1.0] — 2025-04-01
...
```

### Quy tắc viết Release Notes

```
✓ Viết theo góc nhìn USER (impact), không phải góc nhìn dev (implementation)
✓ Breaking changes phải có migration path rõ ràng
✓ Bugfix phải mô tả điều kiện reproduce lỗi
✓ Deprecated features phải có deadline xóa

❌ "Refactored authentication module"
✅ "Cải thiện: Đăng nhập nhanh hơn 2x, giảm từ 3s → 1.5s"

❌ "Fixed null pointer exception in user service"
✅ "Sửa lỗi: App crash khi đăng nhập bằng Google trên Android 12"

❌ "Removed legacy code"
✅ "Deprecated: API /api/v1/export — sẽ xóa ngày 01/09/2025. Dùng /api/v2/export thay thế"
```

---

## Module 4 — Change Impact Matrix

**Dùng khi:** Một tính năng thay đổi và cần biết cần update docs nào.

```
THAY ĐỔI TÍNH NĂNG: [Tên thay đổi]
Loại: ☐ Thêm mới  ☐ Sửa đổi  ☐ Xóa bỏ  ☐ Breaking change

Modules cần cập nhật:
┌─────────────────────────────┬────────────┬──────────────────────┐
│ Module                      │ Cần update?│ Nội dung cập nhật    │
├─────────────────────────────┼────────────┼──────────────────────┤
│ PRD / Feature Spec          │ ☐ Có  ☐ Ko │                      │
│ User Guide (End User)       │ ☐ Có  ☐ Ko │                      │
│ Admin Guide                 │ ☐ Có  ☐ Ko │                      │
│ Onboarding / Tutorial       │ ☐ Có  ☐ Ko │                      │
│ FAQ / Troubleshooting       │ ☐ Có  ☐ Ko │                      │
│ Release Notes / Changelog   │ ☐ Có  ☐ Ko │ Luôn cần             │
│ README / Quick Start        │ ☐ Có  ☐ Ko │                      │
│ API Documentation           │ ☐ Có  ☐ Ko │                      │
│ In-app help text / tooltips │ ☐ Có  ☐ Ko │                      │
└─────────────────────────────┴────────────┴──────────────────────┘
Người chịu trách nhiệm: _______________  Deadline: _______________
```

---

## Proactive Sync Triggers

Codex nên chủ động nhắc cập nhật docs khi phát hiện:

```
Code trigger                      → Hỏi về docs
─────────────────────────────────────────────────────
Thêm API endpoint mới             → "Cần cập nhật API docs?"
Đổi UI text / button label        → "Cần cập nhật User Guide step?"
Thay đổi permission/role          → "Cần cập nhật Admin Guide?"
Xóa tính năng                     → "Cần thêm Deprecated section?"
Thay đổi flow đăng nhập           → "Cần cập nhật Onboarding docs?"
Breaking change trong API         → "Cần migration guide trong changelog?"
Thêm error message mới            → "Cần thêm vào Troubleshooting?"
Thay đổi pricing/tier             → "Cần cập nhật feature comparison table?"
```

---

## Quy tắc viết chung

### Ngôn ngữ
```
✓ Tiếng Việt đơn giản, tự nhiên — không dịch máy
✓ Active voice: "Bạn nhấn nút X" — không phải "Nút X được nhấn bởi bạn"
✓ Present tense cho mô tả tính năng: "Tính năng X cho phép..."
✓ Numbered list cho steps, bullet cho options/features
✓ Bold cho tên button, field, menu — `code style` cho technical terms
```

### Version và Metadata
```
✓ Mỗi doc file phải có: version, ngày cập nhật, author
✓ Tăng version khi có thay đổi nội dung (không chỉ format)
✓ Semantic versioning cho PRD: 1.0 = approved, 1.1 = minor update, 2.0 = major revision
✓ "Last updated" phải phản ánh thực tế — không để stale date
```

### Review Checklist trước khi publish
```
☐ Thông tin có còn đúng với version hiện tại?
☐ Tất cả steps có thể follow được end-to-end?
☐ Screenshots/examples match UI hiện tại?
☐ Links không bị broken?
☐ Spelling và grammar được check?
☐ Người không quen dự án có hiểu được không?
```