---
name: non-tech-document-rewriter
description: >-
  Rewrite technical and business documents so PMs, BAs, customers, managers,
  and non-specialists can understand them without changing meaning or losing
  information. Use when asked to make content easier to understand, update
  presentation for non-tech readers, simplify wording, preserve format while
  rewriting, improve a proposal for customer approval, or shorten an overview.
  Recognize Vietnamese requests such as “update lại trình bày cho dễ hiểu”,
  “người không chuyên cũng hiểu”, “giữ nguyên format”, and “bỏ dạng bảng”.
---

# Non-Tech Document Rewriter

> Business terminology: follow `custom/rules/domain-terminology.md` and `AK-Docs/00.Project-Overview/Glossary.md` — use exactly the terms earlier documents of the same functionId/ticket already use (QnA-Log, Analysis, UC Spec, System Requirement, requirement.md, test case), no synonyms; never translate a project term (`buyer`, `group`, `product`...); never coin your own name for a subsystem, menu or screen area; write a Japanese term as its Glossary `Viết trong tài liệu` name with the original in brackets at first use, and original-first where the reader must match on-screen text. Rewriting for non-specialists never means replacing these terms — keep them, explain them once if needed.
> UI action verbs and IT terms: follow `custom/rules/ui-action-wording.md` (inherited from `qa-writing-standards.md` §6.11) — action sentences use the standard verbs (`Click button`, `Click menu item`, `Enter <value> into <field>`, `Select`, `Check`, `Open modal`, `Press Enter`…), result sentences use the standard states (`Displayed`, `Enabled` / `Disabled`, `Checked`…), IT terms stay in English (field, button, toast, modal, server, cache, redirect, validate…); in Vietnamese output never write "bấm", "nhấn", "tích chọn", "chọn tay", "máy chủ", "bộ nhớ đệm". Business sentences stay in the output language.

## 1. Mục tiêu

Biên tập tài liệu để người đọc hiểu rõ vấn đề, cách giải quyết, tác động và điều cần quyết định. Giữ đúng ý nghĩa, nghiệp vụ và mức độ chắc chắn của bản gốc.

Mặc định viết bằng ngôn ngữ của tài liệu nguồn. Ưu tiên tiếng Việt khi nguồn và yêu cầu đều bằng tiếng Việt. Không tự dịch tài liệu nếu người dùng chỉ yêu cầu chỉnh trình bày.

## 2. Thứ tự ưu tiên

Áp dụng theo thứ tự:

1. Yêu cầu cụ thể và phạm vi đã được người dùng cho phép.
2. Tính chính xác và đầy đủ của tài liệu nguồn hiện tại.
3. Các phần được yêu cầu giữ nguyên.
4. Khả năng hiểu và đọc nhanh của đối tượng nhận tài liệu.
5. Các mẫu trình bày trong skill này.

Không áp dụng một mẫu cố định nếu mẫu đó làm sai cấu trúc hoặc ý nghĩa gốc. Nếu đã có yêu cầu cập nhật rõ ràng, thực hiện trực tiếp. Chỉ đề xuất và chờ duyệt khi người dùng yêu cầu “đề xuất trước, OK rồi mới update”.

## 3. Nguyên tắc bảo toàn thông tin

- Giữ số liệu, đơn vị, công thức, điều kiện, ngoại lệ, phạm vi, thời gian, phiên bản, trách nhiệm và phụ thuộc.
- Giữ đầy đủ link tham khảo, ticket, trích dẫn, evidence và liên kết nội bộ. Có thể sửa cú pháp Markdown nhưng không tự đổi URL đích.
- Giữ phân biệt giữa hiện trạng, đề xuất, giả định, kết quả đo được và việc cần xác nhận.
- Không biến “dự kiến”, “có thể”, “giúp hạn chế” thành “đã làm”, “chắc chắn”, “đảm bảo”.
- Không thêm cam kết như “đủ mọi testcase”, “không còn lỗi”, “chính xác 100%” nếu nguồn không chứng minh.
- Không đổi ý nghĩa nghiệp vụ để câu văn dễ đọc hơn.
- Không tự thêm số liệu, chi phí, thời hạn, lợi ích định lượng hoặc kết luận.
- Không tự xóa nội dung quan trọng. Viết dễ hiểu hơn không đồng nghĩa với tóm tắt.
- Chỉ xóa phần thừa, gộp nội dung trùng hoặc rút bớt chi tiết khi người dùng cho phép. Không làm mất điều kiện và ngoại lệ khi gộp.
- Không tự giải quyết mâu thuẫn giữa các số liệu. Giữ thông tin liên quan và đánh dấu ngắn gọn “Cần xác nhận” nếu chưa có căn cứ.

## 4. Quy trình thực hiện

### Bước 1 — Đọc nguồn và xác định phạm vi

Đọc đầy đủ phần cần sửa từ tài liệu hiện tại. Không dùng bản cũ hoặc nội dung nhớ được thay cho file hiện hành.

Xác định từ yêu cầu và ngữ cảnh:

- Người đọc: khách hàng, quản lý, PM/BA, Dev/QA hoặc người không chuyên ngành.
- Mục đích: thông báo, giải thích, release note, proposal, hướng dẫn hay xác nhận nghiệp vụ.
- Chế độ: chỉ chỉnh câu chữ; tổ chức lại; rút gọn; bỏ bảng; hoặc giữ nguyên format.
- Phạm vi được sửa và phần phải giữ nguyên, đặc biệt phụ lục code, evidence, heading và bảng.

Nếu đã đủ thông tin, tiến hành với lựa chọn hợp lý. Nếu thiếu tài liệu nguồn hoặc thông tin có thể làm thay đổi nghiệp vụ, hỏi đúng phần còn thiếu; không đoán.

### Bước 2 — Lập danh sách nội dung cần giữ

Ghi nhận các ý chính, số liệu, điều kiện, thuật ngữ, URL, ticket và phần được bảo vệ. Dùng danh sách này để đối chiếu sau khi sửa; không cần đưa toàn bộ danh sách vào kết quả cho người dùng.

### Bước 3 — Chọn cấu trúc phù hợp

Nếu được phép tổ chức lại, ưu tiên:

- Giải thích cải tiến: **Vấn đề → Thay đổi → Kết quả/giá trị**.
- Proposal: **Hiện trạng → Vấn đề → Đề xuất → Lợi ích → Rủi ro/điều kiện → Cần quyết định gì**.
- Overview: **Có gì mới → Vì sao quan trọng → Ai được lợi**.
- Xác nhận nghiệp vụ: **Cần xác nhận gì → Vì sao cần → Đề xuất nếu có → Ảnh hưởng nếu chưa xác nhận**.
- Hướng dẫn: **Ai thực hiện → Làm gì → Khi nào → Kết quả cần có**.

Chỉ sử dụng các thành phần có dữ liệu nguồn. Không tự tạo vấn đề, rủi ro hoặc phương án chỉ để điền đủ mẫu.

### Bước 4 — Biên tập câu chữ

Viết câu ngắn, chủ ngữ rõ, mỗi đoạn tập trung vào một ý. Ưu tiên mô tả hành vi và tác động mà người đọc quan tâm.

Giải thích thuật ngữ ở lần xuất hiện đầu tiên bằng một cụm ngắn. Giữ thuật ngữ chuyên môn cần thiết để người đọc đối chiếu với tài liệu khác.

Thay tên class/function bằng mô tả nghiệp vụ trong phần chính nếu cấu trúc cho phép. Giữ chi tiết kỹ thuật làm evidence hoặc đưa xuống phụ lục khi được phép di chuyển. Không bỏ lệnh, đường dẫn hoặc tên cấu hình cần thiết để thực hiện công việc.

Dùng ví dụ cụ thể khi giúp hiểu rõ một quy tắc. Nếu ví dụ không có trong nguồn, ghi rõ “Ví dụ minh họa”; không trình bày như số liệu dự án.

Thống nhất thuật ngữ theo lựa chọn của người dùng, chẳng hạn dùng “mask/masking” xuyên suốt thay vì xen kẽ với “che”. Không sửa literal code hoặc trích dẫn được yêu cầu giữ nguyên.

### Bước 5 — Kiểm tra và giao kết quả

Đối chiếu bản sửa với nguồn theo checklist ở mục 9. Nếu chỉnh file, lưu đúng định dạng và kiểm tra phần hiển thị bằng công cụ phù hợp khi có.

Giao bản đã sửa hoàn chỉnh, thay vì chỉ hướng dẫn người dùng nên viết thế nào. Nếu người dùng yêu cầu file, tạo file và cung cấp liên kết tải. Không tuyên bố đã sửa hoặc lưu file nếu mới đưa bản nháp trong chat.

Nêu ngắn gọn thay đổi chính và điểm cần xác nhận nếu có. Không thêm phần giải thích biên tập dài vào chính tài liệu gửi khách hàng.

## 5. Quy tắc trình bày

### Heading và đoạn văn

- Giữ nguyên heading và thứ tự mục khi được yêu cầu.
- Khi được phép đổi, dùng heading ngắn, nói rõ nội dung.
- Không chia một ý đơn giản thành quá nhiều heading.
- Dùng đoạn ngắn và danh sách cho các ý song song hoặc bước thực hiện.
- In đậm điểm quan trọng có chọn lọc; tránh in đậm toàn bộ đoạn.
- Chỉ dùng emoji hoặc dấu “→” khi phù hợp phong cách nguồn hoặc yêu cầu.

### Bảng

Dùng bảng khi cần so sánh, đối chiếu hoặc thể hiện chính xác các trường dữ liệu. Không ép nội dung giải thích dài vào bảng.

Khi người dùng yêu cầu bỏ bảng, chuyển mỗi dòng thành một mục và giữ đủ nội dung của các cột, kể cả link, điều kiện và ngoại lệ. Không để sót phần sau bảng.

### Markdown

- Dùng heading thật như `## Tiêu đề`; không bọc cả heading trong dấu in đậm.
- Dùng link `[Tên](URL)` và giữ nguyên URL.
- Đặt một dòng trống trước/sau danh sách, bảng và code block.
- Đóng đầy đủ code fence, dùng language phù hợp như `bash` hoặc `json`.
- Sửa ký tự escape hoặc HTML entity gây lỗi hiển thị bên ngoài literal code khi cần; không giải mã mù quáng trong code.
- Không thêm thuộc tính riêng của giao diện chat vào code fence trong file Markdown.

### Giữ nguyên format

Khi được yêu cầu giữ nguyên format/bố cục, chỉ sửa câu chữ trong vị trí hiện có. Giữ heading, đánh số, thứ tự section, kiểu danh sách, cấu trúc bảng và vị trí phụ lục.

Nếu đồng thời có yêu cầu “giữ nguyên format” và “bỏ bảng”, áp dụng ngoại lệ bỏ bảng cho phần được chỉ định, giữ cấu trúc phần còn lại. Hỏi lại nếu hai yêu cầu thực sự không thể đồng thời đáp ứng.

## 6. Hướng dẫn theo loại tài liệu

### Proposal cho khách hàng hoặc quản lý

Viết thành đề xuất mà khách hàng có thể đọc trực tiếp, không thành hướng dẫn thuyết trình cho người viết.

Làm rõ việc cần phê duyệt: phương án, phạm vi, nguồn lực hoặc giai đoạn nào. Giữ rủi ro, giả định và các điều kiện chưa xác nhận để người đọc quyết định có căn cứ. Không tô hồng kết quả hoặc tạo áp lực phê duyệt.

### Release note và overview

Giữ overview ngắn hơn phần chi tiết. Mỗi cải tiến gồm tên, ticket và một đoạn ngắn giải thích thay đổi cùng giá trị. Giữ lệnh cài đặt/cập nhật khi nguồn có; không tự sửa phiên bản hoặc command.

Không đưa tính năng mới vào đoạn tổng kết nếu phần nguồn không có. Không lặp lại toàn bộ nội dung bằng một mục “Tóm lại” dài.

### Tài liệu kỹ thuật hoặc chuyên ngành

Giải thích thuật ngữ theo vai trò thực tế. Phân biệt tên sàn, chỉ số, sản phẩm và đơn vị đo; không gọi một mức giá là tên sàn. Giữ công thức chính xác và giải thích biến ngay cạnh công thức nếu cần.

Chỉ tra cứu khi nhiệm vụ yêu cầu kiểm chứng, nguồn thiếu định nghĩa cần thiết hoặc có nghi vấn về độ chính xác. Ưu tiên nguồn chính thức. Tách rõ thông tin bổ sung đã kiểm chứng khỏi nội dung gốc; không biến một tác vụ biên tập thành nghiên cứu ngoài phạm vi.

### Phụ lục code và evidence

Nếu người dùng yêu cầu giữ nguyên, không sửa code, command, path, log hoặc nội dung phụ lục. Đối chiếu phần được bảo vệ trước và sau khi sửa. Chỉ thay đổi khi được cho phép rõ ràng.

## 7. Ví dụ trước–sau

### Diễn đạt hành vi thay cho tên hàm

**Trước:** `TokenTransferService::assertNotSelfTransfer()` kiểm tra self-transfer.

**Sau:** Hệ thống không cho phép người dùng chuyển token cho chính ví của mình.

Giữ tên hàm trong evidence nếu tài liệu cần truy vết kỹ thuật và được phép di chuyển nội dung.

### Giải thích thuật ngữ

**Trước:** Model chạy shadow mode để so sánh baseline.

**Sau:** AI chạy thử song song với hệ thống hiện tại và chưa tác động đến kết quả gửi người dùng. Kết quả của hai bên được so sánh để đánh giá hiệu quả. Cách chạy thử này gọi là **shadow mode**; kết quả của hệ thống hiện tại dùng làm **mốc so sánh (baseline)**.

Chỉ dùng cách diễn đạt này nếu đúng cơ chế trong tài liệu nguồn.

### Release note không dùng bảng

**Trước:** Dev Checklist — hệ thống sinh checklist ngoài Test Case cho QA.

**Sau:**

#### Dev Checklist (mới)

Ngoài Test Case cho QA, hệ thống sinh thêm checklist để Dev tự kiểm trước khi bàn giao, giúp phát hiện sớm lỗi cơ bản và giảm vòng trả lại giữa QA và Dev.

Giữ ticket và URL nếu có trong nguồn. Không thêm nhận định “Dev biết toàn bộ nội dung QA sẽ kiểm” nếu nguồn không xác nhận.

### Ví dụ minh họa cho phạm vi test

**Trước:** Cần khai báo dimension expansion.

**Sau:** Cần khai báo những thiết bị, ngôn ngữ và biến thể phải kiểm tra để AI sinh testcase phù hợp. **Ví dụ minh họa:** nếu mọi tổ hợp đều cần test, 3 biến thể × 2 ngôn ngữ × 3 thiết bị tạo thành 18 tổ hợp cần kiểm tra.

Không kết luận luôn cần 18 testcase: một tổ hợp có thể cần nhiều testcase, hoặc không cần tách case riêng tùy chiến lược test.

## 8. Các lỗi cần tránh

- Xóa link tham khảo khi rút gọn câu.
- Bỏ điều kiện hoặc ngoại lệ để đoạn văn ngắn hơn.
- Tự thay đổi heading khi người dùng yêu cầu giữ nguyên.
- Đưa tên function/class dày đặc vào slide cho người không chuyên.
- Đổi từ ngữ trong phần code hoặc phụ lục được bảo vệ.
- Viết “cách trình bày proposal” thay vì proposal hoàn chỉnh.
- Lặp lại toàn bộ tài liệu trong overview.
- Thêm tính năng hoặc lợi ích chưa có căn cứ vào đoạn tổng kết.
- Biến ví dụ giả định thành dữ liệu thực tế.
- Nhầm giữa “chỉnh trình bày”, “rút gọn” và “thay đổi nội dung”.
- Hỏi xác nhận lại cho một cập nhật đã được người dùng cho phép.

## 9. Checklist kiểm tra cuối

- [ ] Đã sửa đúng phạm vi và phục vụ đúng đối tượng đọc.
- [ ] Không mất ý nghĩa, thông tin quan trọng, điều kiện hoặc ngoại lệ.
- [ ] Số liệu, đơn vị, công thức, thời gian và phiên bản khớp nguồn.
- [ ] Link, ticket, evidence và tham chiếu nội bộ được giữ đầy đủ.
- [ ] Không biến giả định hoặc đề xuất thành kết luận chắc chắn.
- [ ] Thuật ngữ khó được giải thích ngắn và dùng nhất quán.
- [ ] Cấu trúc và phần được bảo vệ giữ đúng yêu cầu.
- [ ] Phần chính tập trung vào hành vi, vấn đề và tác động dễ hiểu.
- [ ] Overview ngắn; proposal nêu rõ điều cần quyết định nếu nguồn có.
- [ ] Markdown hợp lệ; không còn bảng nếu đã được yêu cầu bỏ bảng.
- [ ] Không có số liệu, lợi ích hoặc cam kết tự thêm.
- [ ] Đã tạo/lưu đúng kết quả được yêu cầu trước khi thông báo hoàn thành.
