ignify-docs

name	ignify-docs
description	Soạn thảo văn bản nội bộ Ignify (.docx) đúng form mẫu công ty — logo, cover page, heading đỏ

Soạn văn bản Ignify

Viết nội dung dưới dạng doc-source markdown, rồi build ra .docx bằng script kèm theo. Script mở file mẫu thật của công ty (assets/ignify-template.docx — bản export đã được duyệt, đã xoá phần thân nhưng giữ nguyên logo, style, font nhúng) và ghi nội dung vào đó. Vì vậy output trùng form mẫu chứ không phải "trông giống" — đừng tự dựng .docx từ đầu bằng python-docx, đừng tự chọn màu/font, và đừng sửa file trong assets/.

Quy trình

1. Hỏi cho đủ trước khi viết. Tài liệu sai vì thiếu thông tin, không phải vì sai format. Cần biết: loại văn bản, người đọc là ai, phạm vi áp dụng, ai ban hành, phiên bản/ngày. Nếu user đã đưa nguồn (ghi chú, chat, code, doc BA, ticket) thì đọc kỹ và chỉ hỏi phần còn thiếu. Nếu user bảo "cứ làm đi" thì tự điền giả định hợp lý và liệt kê giả định đó ở cuối câu trả lời để họ sửa, thay vì chặn lại để hỏi.

2. Chọn khung theo loại văn bản. Xem references/doc-types.md — có skeleton cho hướng dẫn sử dụng, quy trình/quy định, báo cáo, đề xuất, biên bản họp, tài liệu nghiệp vụ. Đừng bịa cấu trúc mới nếu một khung có sẵn đã hợp.

3. Viết .md theo dialect bên dưới. Lưu cạnh file đích (VD huong-dan-x.md) — giữ lại file nguồn để lần sau sửa nội dung không phải gõ lại từ đầu.

4. Build. SKILL_DIR là thư mục chứa chính file SKILL.md này — tuỳ cách cài mà nó nằm ở .claude/skills/ignify-docs/ (cài cho project) hoặc ~/.claude/skills/ignify-docs/ (cài global). Dùng đường dẫn tuyệt đối tới đó, đừng đoán:

   python3 <SKILL_DIR>/scripts/build_docx.py nguon.md "Tên tài liệu.docx"
   

   Script cần python-docx. Thiếu thì pip install python-docx.

5. Nhìn kết quả trước khi báo xong. Render và đọc bằng mắt — bảng vỡ cột, callout tràn trang, heading nhảy số là những lỗi chỉ lộ ra khi nhìn:

   libreoffice --headless --convert-to pdf "Tên tài liệu.docx" --outdir /tmp/ >/dev/null 2>&1
   pdftoppm -png -r 80 /tmp/"Tên tài liệu".pdf /tmp/page
   

   Rồi Read các file /tmp/page-*.png. Nếu có gì lệch, sửa .md và build lại.

6. Báo cáo: đường dẫn .docx, số trang, và các giả định đã tự điền.

Doc-source dialect

Front matter — title là loại văn bản (viết hoa), subtitle là chủ đề cụ thể:

---
title: TÀI LIỆU HƯỚNG DẪN
subtitle: Quản lý dự án trên PMO Board
org: PMO – Bộ phận Quản lý Dự án
version: 1.0
date: 07/2026
scope: Toàn bộ PM trong công ty
---

cover: false bỏ trang bìa — dùng cho văn bản ngắn 1–2 trang (biên bản họp, memo). Mặc định có bìa.

Thân bài dùng markdown thường:

Cú pháp	Ra cái gì
# 1. Giới thiệu	Heading 1, đỏ #980000 — mỗi mục lớn, tự đánh số
## 2.1 Tổng quan	Heading 2, navy
### 2.1.1 Chi tiết	Heading 3, xanh
- item	Bullet •; thụt 2 space cho bullet con
1. bước	Danh sách đánh số
| a | b | + |:---|:---|	Bảng: header đỏ chữ trắng, dòng kẻ sọc
**đậm** *nghiêng* `mã` [chữ](url)	Định dạng inline

Bốn loại callout box — đây là thứ làm văn bản đọc ra "của Ignify":

:::note Lưu ý
Không được chuyển thẳng từ Backlog sang Done.
:::

:::box Template comment cập nhật tuần
Cập nhật [ngày/tháng]
Đã hoàn thành:
   - [việc 1]
:::

:::highlight Bước 2 – Thực hiện Sprint
→ Tạo item [Task]: "Sprint 1 – Tháng 05/2026"
:::

:::code Cấu trúc phân cấp
EPIC  =  Dự án (Project)
   └─  Task  =  Sprint đang thực hiện
:::

• note (vàng) — cảnh báo, ràng buộc, "Lưu ý", "Ghi chú". Cái người đọc phải biết kẻo làm sai.
• box (hồng) — mặc định: template điền sẵn, ví dụ mẫu, một bước trong quy trình.
• highlight (cam) — xen kẽ với box khi liệt kê nhiều bước liên tiếp, để mắt phân biệt được các bước.
• code (hồng, chữ đơn cách) — sơ đồ cây, cấu trúc, snippet. Chữ đơn cách nên ASCII art thẳng hàng.

Nội dung trong callout giữ nguyên xuống dòng và thụt lề — cứ viết như bạn muốn nó hiện ra. Riêng :::code chỉ vừa ~72 ký tự một dòng; dài hơn sẽ bị wrap và sơ đồ mất thẳng hàng. Tự ngắt dòng cho vừa thay vì để Word ngắt hộ.

Tiêu đề heading, tiêu đề callout và ô header của bảng luôn in đậm sẵn theo style, nên **, *, ` trong đó bị bỏ đi — viết chữ thường, đừng đánh dấu markdown.

Cột bảng được chia tự động theo độ dài nội dung. Muốn ép, đặt ngay trên bảng (tổng phải bằng 468pt): <!-- widths: 110,184,174 -->

Xem references/example-huong-dan.md — bản dựng lại tài liệu PMO Board bằng đúng dialect này. Đọc nó khi cần biết một tài liệu "đạt chuẩn" trông ra sao.

Giọng văn

Đây là văn bản hành chính nội bộ, có thể được ban hành, viện dẫn, hoặc đính kèm hợp đồng. Nó phải đọc như văn bản công ty, không phải như tin nhắn Slack hay README trên GitHub.

Tuyệt đối không emoji, không icon trang trí (✅ ❌ 🚀 ⚠️ 🎉 …). Không có ngoại lệ — kể cả trong bảng để đánh dấu đúng/sai, kể cả trong checklist. Cần đánh dấu thì dùng chữ: "Có / Không", "Đạt / Không đạt", "Bắt buộc / Tuỳ chọn". Một dấu tích emoji trong bảng làm cả tài liệu mất tư cách văn bản chính thức.

Mũi tên → và ký tự vẽ cây └─ ├─ được phép — tài liệu mẫu dùng chúng trong sơ đồ luồng và box các bước. Đó là ký hiệu kỹ thuật, không phải emoji. Nhưng chỉ dùng trong :::code và :::box mô tả luồng, đừng rải vào văn xuôi.

Giọng trang trọng, vô nhân xưng. Chủ ngữ là vai trò, không phải người cụ thể:

Viết thế này	Không viết thế này
PM cập nhật trạng thái item chậm nhất vào thứ Sáu hằng tuần.	Anh/em nhớ update status trước cuối tuần nhé.
Reviewer phản hồi trong vòng 24 giờ làm việc.	Bạn reviewer cố gắng rep sớm giúp mình.
Trường hợp quá hạn, Tech Lead thực hiện review thay.	Nếu lâu quá thì nhờ tech lead review hộ.
Không được merge khi CI chưa xanh.	Đừng merge lúc CI còn đỏ ok?

Cụ thể: không dùng "mình", "bạn", "nhé", "ok", "luôn nha", không dùng câu cảm thán hay dấu chấm than. Không viết tắt kiểu chat (ko, dc, vs, sp). Câu khẳng định, dứt khoát — "phải", "không được", "chậm nhất là", chứ không phải "nên", "cố gắng", "tốt nhất là".

Xưng hô trong tài liệu dùng chức danh/vai trò (PM, Reviewer, Tech Lead, NVKD, Bộ phận Kinh doanh), kể cả khi nguồn đầu vào (chat, ghi chú họp) gọi nhau bằng "anh Tuấn", "chị Hà". Riêng biên bản họp thì giữ tên người ở mục thành phần tham dự và bảng phân công — vì biên bản cần định danh ai chịu trách nhiệm — nhưng phần nội dung trao đổi vẫn viết trang trọng.

Viết cái gì vào đó

Format chỉ là vỏ. Văn bản Ignify đọc được là nhờ mấy thói quen sau — lấy từ tài liệu mẫu:

Mở đầu bằng mục đích, không phải bối cảnh. Mục 1 luôn trả lời "đọc xong cái này thì làm được gì" trong 1–2 câu, rồi tới Mục tiêu: + bullet. Người đọc là đồng nghiệp bận, không phải người lạ cần dẫn nhập.

Câu ngắn, chủ động, có chủ ngữ là người chịu trách nhiệm. "PM cập nhật trạng thái item" chứ không phải "Trạng thái item cần được cập nhật". Ai làm gì phải rõ.

Sự thật liệt kê được thì cho vào bảng, đừng viết thành đoạn. 4 cột Kanban, 3 loại issue, 5 quy ước đặt tên — bảng. Ngược lại, đừng nhét lý giải dài vào ô bảng; giải thích để ở đoạn văn ngay trên bảng.

Có ví dụ cụ thể, tên thật. Tài liệu mẫu dùng thẳng "BIDV DVC5", "Sprint 3 – Tháng 07/2026". Ví dụ trừu tượng kiểu "Dự án A" khiến người đọc không biết mình có đang làm đúng không.

Cái gì người đọc phải gõ/điền thì đưa vào :::box dưới dạng template điền sẵn với placeholder [trong ngoặc vuông]. Đừng mô tả bằng lời cái mà bạn có thể đưa thẳng mẫu.

Giữ nguyên thuật ngữ tiếng Anh đã dùng quen (Backlog, In Progress, Epic, Sprint, Assignee, Due date, deploy, review). Dịch ép sang tiếng Việt làm tài liệu khó đối chiếu với giao diện thật.

Kết bằng một ví dụ chạy hết vòng đời nếu tài liệu mô tả quy trình — chuỗi :::box / :::highlight xen kẽ, mỗi box một bước, nối bằng →. Đó là phần người đọc mở lại nhiều nhất.

Đừng viết mục rỗng. Nếu không có nội dung thật cho "Rủi ro" hay "Phụ lục", bỏ mục đó đi. Một tài liệu 4 mục chắc còn hơn 9 mục toàn placeholder.

Sửa tài liệu đã có

Nếu file .md nguồn còn: sửa .md, build lại, xong.

Nếu chỉ còn .docx: đọc nó ra markdown trước rồi mới sửa — python3 <SKILL_DIR>/scripts/docx_to_source.py cu.docx cu.md dựng lại doc-source từ file .docx đã build, kể cả callout và bảng. Sửa cu.md, build lại. Đừng chỉnh sửa .docx trực tiếp.