Longform Report — Skill (2 mode: article + atlas)

Skill tạo báo cáo tự nghiên cứu HTML với 2 mode tùy theo nhu cầu:

Khi nào chọn mode nào?

• Article: “bài research dài”, “phân tích chương”, “báo cáo” → đọc tuần tự như sách.
• Atlas: “atlas”, “dashboard research”, “bản đồ ngành”, “interactive” → click đổi view, data nhiều bảng quan hệ.

Mỗi sản phẩm đều đứng trên hai trục song song:

• Số liệu thật — mỗi con số có nguồn, đối chiếu được (Bước 5 / A3).
• Học thuật thật — mỗi lý thuyết dẫn đúng tác giả/năm/nội dung gốc (Bước 5b).

Đây là gói skill dành cho các agent (Codex / ZCode / Codex CLI…). Trong agent, skill được gọi qua /longform-report (alias /longform).

---

So sánh 2 mode

---

Cấu trúc

longformskill/
├── SKILL.md                          # Header "Chọn mode" + Workflow 7 bước article + Workflow A1-A7 atlas + 15 pitfall
├── assets/
│   ├── article_template.html         # Template CORE article self-contained ({{TOKEN}} placeholder)
│   └── atlas_template/               # ⭐ MỚI — Template SPA atlas kickoff tối thiểu
│       ├── index.html                # Shell CSS Grid 3 vùng + hash router + 3 view mẫu
│       ├── styles.css                # Tokens + dark/light parity + view primitives + chart wrapper
│       └── app.js                    # IIFE + el() + Promise.all loadData + renderRoute dispose-first
├── references/
│   ├── components.md                 # Article: Catalog component (CORE + nâng cao)
│   ├── chart_recipes.md              # Article: Recipe Chart.js 4.4.1 cho dark theme
│   ├── themes.md                     # Article: Family Amber/Blue + bảng hero gradient mood
│   ├── navigation.md                 # Article: Minimap + progress + presentation
│   ├── citations.md                  # Article: 2 chế độ trích nguồn (numerated vs plain)
│   ├── fact_check.md                 # Article: ⭐ Hậu kiểm số liệu (trục "số liệu thật")
│   ├── academic_foundations.md       # Article: ⭐ Nền tảng học thuật + fact-check lý thuyết
│   ├── translation_vi.md             # Article: ⭐ Hậu kỳ dịch Anh–Việt
│   ├── source_mapping.md             # Article: ⭐ Bản đồ cấu trúc nguồn PDF
│   ├── atlas_architecture.md         # ⭐ MỚI — Atlas: SPA + router + state + el() + dispose + dark/light
│   ├── atlas_charts.md               # ⭐ MỚI — Atlas: ECharts + Cytoscape + 4 SVG builders + chartWrapper
│   ├── atlas_data_schema.md          # ⭐ MỚI — Atlas: 13 file schema + tier A/B/C + confidence 4 mức
│   └── atlas_build_pipeline.md       # ⭐ MỚI — Atlas: build.js + validate 5 gate + check-links
├── scripts/
│   ├── qa_article.js                 # Article: Playwright QA (8 check)
│   ├── translation_check.py          # Article: Hậu kỳ dịch lint
│   ├── qa_atlas.js                   # ⭐ MỚI — Atlas: Playwright QA (9 check) + JS syntax all files + router + dark/light
│   └── validate_atlas_data.js        # ⭐ MỚI — Atlas: Schema validate 5 gate + dangling ref
└── agents/
    └── openai.yaml                   # UI metadata (display_name, short_description, default_prompt)

---

Cài đặt

Skill là một thư mục chứa SKILL.md + các tài nguyên đi kèm. Đặt vào thư mục skills mà agent quét:

ZCode

git clone [email protected]:Thanhtran-165/longformskill.git \
  ~/.zcode/skills/longform-report

Codex / Codex CLI

git clone [email protected]:Thanhtran-165/longformskill.git \
  "${CODEX_HOME:-$HOME/.codex}/skills/longform-report"

⚠️ Tên thư mục phải là longform-report để các lệnh copy template / chạy QA dùng $SKILL_DIR hoạt động đúng (xem phần Đường dẫn bên dưới).

Không cần build, không cần dependency ngoài — trừ khi chạy QA script:

npm install playwright --prefix /tmp/qa-runner
npx playwright install chromium

---

Đường dẫn & portability

SKILL.md dùng biến $SKILL_DIR (thư mục chứa skill) cho mọi lệnh tham chiếu file nội bộ:

cp "$SKILL_DIR/assets/article_template.html" {project}/{slug}/index.html
node "$SKILL_DIR/scripts/qa_article.js" --url=file://{project}/{slug}/index.html --output=/tmp/qa-shots

• ZCode: $SKILL_DIR = ~/.zcode/skills/longform-report
• Codex: $SKILL_DIR = ${CODEX_HOME:-~/.codex}/skills/longform-report
• Nếu skill nằm chỗ khác → đặt SKILL_DIR bằng đường dẫn thực tế trên máy.

---

Cách dùng (trong agent)

Mode ARTICLE (mặc định)

/longform-report "BĐS dòng tiền VN" 15 chương

Workflow 7 bước article (agent tự chạy theo SKILL.md):

Mode ATLAS (mới)

/longform-report atlas "Bản đồ ngành AI Việt Nam"

Workflow 7 bước atlas (A1-A7):

Tone cốt lõi (cả 2 mode): “Người kể chuyện số liệu, KHÔNG cho ý kiến” — mô tả quan sát và tỷ lệ, không khuyên mua/bán.

---

Hai trục chất lượng

Catalog lý thuyết đã verify sẵn trong academic_foundations.md (Kahneman, Cialdini, Shefrin & Statman, Dunning-Kruger, Festinger…) — kèm link nguồn gốc để copy đúng tên + tác giả + năm.

---

Phối hợp hệ sinh thái skill (optional)

---

License

Cung cấp nguyên mục đích chia sẻ / tái sử dụng. Bạn tự chịu trách nhiệm về tính chính xác của số liệu và lý thuyết trong các bài báo cáo mình tạo ra (skill có sẵn quy trình fact-check ở Bước 5 & 5b — hãy chạy nó).