feat(tech-writing): skill viết tài liệu kỹ thuật + thay 4 template rỗng

[nguyenthienthanh]

Vấn đề

Aura-frog chỉ có skill documentation phủ ADR + Runbook. Bốn template phase-1 mà scaffold-phase-deliverables.sh sinh ra là khung rỗng:

• lld.md dán cứng ví dụ của một dự án khác — ShareModal.tsx, useSharePost.ts, platform: "facebook" | "instagram", Zustand + React Query. Ai dùng cũng phải xoá sạch trước.
• requirements.md có NFR bịa số: < 200ms, 1000 concurrent users — dễ bị copy nguyên.
• confluence-page.md liệt kê FacebookCard / InstagramCard.
• DESIGN_DECISIONS.md ánh xạ vào lld.md — LLD không phải chỗ ghi quyết định.

Không có template nào cho phân tích kỹ thuật / trade-off, và không mục nào có non-goals, alternatives considered, hay failure modes.

Thay đổi

Skill mới tech-writing, dựng trên 2 lượt deep-research (214 agent, 49 nguồn, ưu tiên nguồn sơ cấp) cộng phần tự verify trực tiếp từ PDF gốc.

Phân tầng T0–T3, mặc định HẠ tầng. Y-statement → ADR Nygard → MADR → RFC. Thứ phân biệt là mức phân tích phương án, không phải độ dài. Kèm vòng đời trạng thái của Oxide RFD (cố tình không có draft) — ra sớm kèm nhãn đúng hơn là giữ lại chờ hoàn hảo.

Grounding trước khi viết, không phải sau. Trích nguyên văn → mọi claim về code phải có file_read trước đó (dùng lại grounding-discipline.md) → claim nào không chống lưng được thì xoá và đánh dấu lỗ hổng, không làm mờ đi.

Cấm tự chấm bản nháp trong chính context bản nháp. Đây là phần ngược trực giác nhất, và là lý do skill không có rubric LLM-tự-chấm — Huang et al., ICLR 2024 (arXiv 2310.01798, Bảng 3):

Model · benchmark	ban đầu	vòng 1	vòng 2
GPT-4 · GSM8K	95.5	91.5	89.0
GPT-3.5 · CommonSenseQA	75.8	38.1	41.8

Cải thiện trong nghiên cứu trước đến từ oracle label và "vanish when oracle labels are not available". Multi-agent debate cùng budget cũng thua self-consistency (83.2@6 vs 85.3@6). Nên skill dùng CoVe với câu hỏi kiểm chứng trả lời ở context riêng, và ưu tiên verifier ngoài (chạy test, gọi API) hơn suy nghĩ nội tại.

Requirements theo bộ ba C/R/A của INCOSE GtWR v4: C1–C9 cá thể, C10–C15 tập hợp, tập con ~10–12 rule lint được bằng máy, A-attributes làm schema truy vết. Ghi rõ INCOSE §1.8 nói công cụ NLP/AI "do not address all the rules" — không quảng cáo "42 kiểm tra tự động".

LLD: nói thẳng là không có chuẩn. IEEE 1016-2009 để ranh giới architecture/HLD/LLD "beyond the scope of this standard". Dùng 12 design viewpoint làm thực đơn, cộng tiêu chí dừng của ECSS: chi tiết tới mức đơn vị "can be coded, compiled, and tested", không hơn. Idempotency / observability / migration-rollback đánh dấu [UNVERIFIED] — không chuẩn công bố nào chống lưng, giữ vì hệ thống cần chứ không vì template có.

Cổng chống AI-slop + nhãn mức bằng chứng [CODE] / [SOURCE] / [CONVENTION] / [UNVERIFIED], và ghi rõ gần như toàn bộ nội dung là quy ước có nguồn sơ cấp, không phải hiệu quả đo được.

Liệt kê 4 niềm tin đã bị bác bỏ để không lọt lại vào skill sau này (Google mandate design-doc gate; 42010 bắt buộc ghi lý do bác phương án; Rust RFC bắt buộc problem-first; adr.github.io có đúng 4 họ template).

File

File	Thay đổi
skills/tech-writing/SKILL.md	mới, 319 dòng
templates/decision-record.md	mới — 4 bậc trong 1 file
templates/lld.md	viết lại
templates/requirements.md	viết lại
templates/confluence-page.md	viết lại
skills/documentation/SKILL.md	ADR chuyển sang tech-writing, giữ Runbook
scripts/workflow/scaffold-phase-deliverables.sh	sửa ánh xạ DESIGN_DECISIONS.md, thêm LLD.md
rules/workflow/workflow-deliverables.md	12 → 14 deliverables

Kiểm chứng

• scripts/audit/audit-refs.sh — không thêm dead-ref nào. 5 dead-ref còn lại (skills/git-worktree, 4 file docs/) đã fail sẵn trên origin/main; không sửa vì ngoài phạm vi PR này.
• Smoke test scaffold-phase-deliverables.sh phase 1 → ra đúng 5 file, không còn ví dụ dán cứng.
• ⚠️ npm test KHÔNG chạy được — jest chưa cài trong môi trường (sh: jest: command not found). Không phải do PR này; thay đổi ở đây là markdown + 1 dòng shell.

Ghi chú cho reviewer

Số LLM-as-judge (Cohen's κ) và ALCE không verify được sau 2 lượt research — SKILL.md ghi rõ cấm trích cho tới khi có ai đó kiểm lại từ paper gốc. Tương tự, chưa xác lập được là có hay không tồn tại benchmark đo chất lượng tài liệu kỹ thuật do AI sinh; phát biểu đúng là "chưa xác lập", không phải "không tồn tại".

Bài học từ quá trình: pass 1 bác claim C1–C15 với 0-3 phiếu vì incose.org trả HTTP 403 — nó coi không lấy được thành không tồn tại. Pass 2 lật ngược 3-0 với trích dẫn nguyên văn. Unreachable ≠ absent.

🤖 Generated with Claude Code