Planning Content

Workflow: Detect & Convert → Interview → Research → Content Map → Outlines → Save → Adjust (nếu cần)

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

Skill CHỈ làm 2 việc: (1) phân tích nội dung input, (2) xác định các ý chính cần cover trong từng bài.
KHÔNG can thiệp cách viết, tone, style, cách sắp xếp section, mở bài, kết bài, framework viết, độ dài bài. Đó là việc của skill viết bài.
KHÔNG viết draft câu mở bài, câu kết, hay bất kỳ phần nào của bài hoàn chỉnh.
Outline = bản đồ ý tưởng, KHÔNG phải bản nháp.
Mọi data point phải cite nguồn (khi có research).
Output tiếng Việt (trừ khi user yêu cầu khác). Thuật ngữ chuyên ngành giữ nguyên gốc trong ngoặc.

Quick Reference

Reference	Mục đích	Load khi
tier-processing.md	Tier detection, batch, subagent, quality gate	Phase 4 (nếu input đã convert)

Phase 1: Detect & Convert Input

1.0 Resolve Skill Paths

Chỉ cần khi input là file hoặc URL cần convert:

Dùng Glob tìm **/planning-content/scripts/wa-env
Chạy: bash {path_to_wa-env}
Parse output lấy: SCRIPTS_DIR, SKILL_DIR, PROJECT_ROOT, OUTPUT_DIR, REFERENCES_DIR

Nếu không tìm thấy wa-env: dùng WebFetch cho URL, Read cho file text. Scripts không bắt buộc.

1.1 Detect Input Type

Input Type	Detection	Action
Topic thuần	Chỉ có chủ đề, không file/URL	→ Phase 2 trực tiếp
Notes/ý tưởng rời	Bullet points, gạch đầu dòng	→ Phase 2 trực tiếp
File (PDF/DOCX/EPUB)	Path + extension	`wa-convert {path}` → content.md + structure.json
File (XLSX/PPTX)	Path + extension	`wa-convert {path}` (qua Docling). Kiểm tra chất lượng, xem tier-processing.md mục "Lưu ý chất lượng conversion"
File (HTML/AsciiDoc)	Path + extension	`wa-convert {path}` (qua Docling)
Image (PNG/JPEG/TIFF/BMP/WEBP)	Path + extension	Dùng Read tool (multimodal) để đọc ảnh trực tiếp. Nếu cần text extraction: `wa-convert {path}` (OCR qua Docling)
URL (web page)	`http://` hoặc `https://` (không YouTube)	Ưu tiên `WebFetch`. Dùng `wa-convert {url}` khi WebFetch trả nội dung rác
YouTube URL	`youtube.com` hoặc `youtu.be`	`wa-convert {url}`
Plain text / .txt / .md	Không extension phức tạp	Read trực tiếp, hoặc `wa-paste-text` nếu cần lưu vào output dir

1.2 File/URL Conversion

# Auto-generate output dir
{SCRIPTS_DIR}/wa-convert /path/to/file.pdf

# Custom output dir
{SCRIPTS_DIR}/wa-convert /path/to/file.pdf my-project/input-handling

Output: content.md + structure.json trong output dir.

Lưu ý venv: Scripts dùng venv riêng tại {SCRIPTS_DIR}/.venv/. Nếu chưa setup, chạy bash {SCRIPTS_DIR}/setup.sh trước.

1.3 Multi-Input

Khi user đưa nhiều file/URL cùng lúc:

Xử lý tuần tự, mỗi input tạo thư mục riêng.
Sau khi convert xong, hỏi user: gộp thành 1 content map chung hay tách riêng từng bộ outline?

1.4 Fallback (không có scripts)

URL: dùng WebFetch trực tiếp
File text (.md/.txt): dùng Read trực tiếp
PDF/DOCX/EPUB/XLSX/PPTX: báo user chạy bash {SCRIPTS_DIR}/setup.sh

Error Handling

Lỗi	Xử lý
File not found	Hỏi lại path
Unsupported format	Báo user, đề xuất convert thủ công
URL fetch failed	Báo lỗi, dừng
Empty content	Cảnh báo, xác nhận trước khi tiếp
Encrypted PDF	Hỏi bản giải mã
YouTube không có transcript	Báo user, hỏi có muốn dùng WebSearch research topic thay thế không

Phase 2: Interview

Hỏi tất cả câu hỏi trong 1 lượt:

Audience: Người đọc chính là ai?
Goal: Mục tiêu chính? (educate / engage / convert / thought leadership)
Scope: Góc cụ thể nào của chủ đề? (mặc định: bao phủ toàn bộ nội dung input)
(Optional) Số bài: User muốn bao nhiêu bài? (mặc định: tự tính)
(Optional) Constraints: Yêu cầu đặc biệt (deadline, topic cần tránh, kênh đăng, ngôn ngữ output)

Fast-track: Nếu input đã đủ context hoặc user yêu cầu "làm luôn", giả định sensible defaults và sang Phase 3.

Edge Cases

Input quá ngắn (1-2 câu): Hỏi user bổ sung context hoặc dùng web research mở rộng.
Thiếu data cho 1 ý: Note "Open questions" trong outline để writer biết cần tìm thêm.
Topic quá rộng: Yêu cầu user chọn góc cụ thể trước khi plan.

Phase 3: Research (Conditional)

Khi nào chạy

Luôn chạy: input là topic thuần, notes/ý tưởng rời
Chạy nếu cần: tài liệu convert nhưng nội dung mỏng, YouTube transcript ngắn/thiếu context
Skip: tài liệu đã convert có nội dung đầy đủ (sách, report dài, tài liệu chuyên sâu)

Tiêu chí "đầy đủ": tài liệu tự cung cấp đủ data, ví dụ, evidence cho các ý chính.

Quy trình

WebSearch 3-5 queries liên quan topic + audience + trends.
Thu thập: data, số liệu, góc nhìn mới, ví dụ thực tế, case study.
Bắt buộc cite nguồn cho mọi data point.

Research ở Phase 3 là tìm bổ sung (trend mới, góc nhìn khác, data gap), KHÔNG phải fetch lại nội dung đã có từ Phase 1.

Phase 4: Map Content & Generate Outlines

4.0 Tier-Aware Processing (chỉ khi input đã convert)

Nếu input đã convert (có structure.json):

Đọc structure.json ONLY (không đọc content.md toàn bộ). Chỉ đọc content.md theo section cụ thể khi cần chi tiết.
Xác định tier. Chi tiết workflow, batch, subagent: xem tier-processing.md.
Nếu structure.json lỗi: xem mục "Fallback" trong tier-processing.md.

4.1 Content Map

Cho topic thuần/notes:

Liệt kê toàn bộ concept/ý lớn từ input + research.
Group các ý liên quan thành cluster theo chủ đề.
Đánh dấu ưu tiên (must-have / nice-to-have).

Cho tài liệu đã convert:

Dùng outline từ structure.json: section titles, word counts, critical markers.
Group sections thành clusters theo heading hierarchy.

4.2 Generate Outlines

Tính số bài:

if user_specified_article_count:
    target = user_specified_count
else:
    target = max(3, round(word_count / 2500))

Ước lượng theo loại input khi không có word count:

Topic thuần → 3-10 bài (tùy scope)
Notes/ý tưởng rời → theo số ý tưởng có sẵn
URL/article → 5-15 bài (tùy độ dài + density)
Sách/tài liệu dài → chia thành batches (~10 bài/batch)

Nguyên tắc lên outline:

1 bài = 1 chủ đề duy nhất. Mỗi outline tập trung đúng 1 ý chính.
Outline = liệt kê ý chính bài cần cover, KHÔNG quy định cấu trúc trình bày.
Mỗi ý chính phải có data/ví dụ hỗ trợ. Ý không có data → đánh dấu "cần tìm thêm" hoặc loại.
Outline phải đủ rõ để writer hiểu bài nói về cái gì mà không cần đoán.
Cho tài liệu đã convert: đọc content.md theo section cụ thể (offset/limit từ structure.json), KHÔNG đọc toàn bộ.

Format mỗi outline:

### Bài [N]: [Tiêu đề đề xuất]

- **Audience:** [Người đọc cụ thể của bài này]
- **Goal:** [Sau khi đọc, reader hiểu hoặc làm được gì]
- **Angle:** [Góc tiếp cận]
- **Thesis (ý cốt lõi):** [1 câu]
- **Key points cần cover:**
  - [Ý chính 1] | data/ví dụ: [...] | nguồn: [...]
  - [Ý chính 2] | data/ví dụ: [...] | nguồn: [...]
  - [Ý chính 3] | data/ví dụ: [...] | nguồn: [...]
- **Takeaway / insight chính:** [Reader rút ra điều gì]
- **Open questions:** [Data còn thiếu. Nếu không có, ghi "Không"]

Phase 5: Save Output

Cấu trúc thư mục:

{CWD}/planning-content/{topic-slug}-{YYMMDD-HHMM}/
├── input-handling/              # Chỉ khi có convert
│   ├── content.md
│   └── structure.json
├── index.md                     # Overview + danh sách link
├── outline-[NN]-[slug].md      # Mỗi bài 1 file
├── research.md                  # Nếu Phase 3 chạy
└── content-map.md               # Nếu input dài hoặc nhiều concepts

index.md format:

# Content Plan: [Topic]

## Overview
- Audience: [...]
- Goal: [...]
- Tổng số bài: [N]
- Nguồn input: [URL/file/topic]
- Word count gốc: [N] (nếu có structure.json)

## Danh sách Outlines
1. [Bài 1: Tiêu đề](outline-01-slug.md)
2. [Bài 2: Tiêu đề](outline-02-slug.md)
...

## Coverage Checklist (nếu batch)
- [x] Batch 1 — 10/10
- [ ] Batch 2 — 0/10

Xử lý input dài (batch):

Tạo content map trước, lưu vào content-map.md.
Batch ~10 bài/batch, làm batch đầu trước.
Coverage check (BẮT BUỘC) sau mỗi batch: đối chiếu content map, liệt kê concept ĐÃ cover vs CHƯA cover. Lặp đến 100%.
Cập nhật index.md sau mỗi batch.
Hỏi user confirm trước batch tiếp.

Cuối cùng hỏi: "Đã hoàn thành outline cho [N] bài. Bạn muốn điều chỉnh outline nào không?"

Phase 6: Adjust Outlines (nếu user yêu cầu)

Yêu cầu	Xử lý
Sửa 1 outline	Đọc file, chỉnh theo feedback, ghi đè
Merge 2+ outlines	Gộp key points, chọn thesis mới, xoá file thừa, cập nhật index.md
Tách 1 outline	Chia key points thành groups, tạo file mới, cập nhật index.md
Thêm outline mới	Tạo file theo format Phase 4.2, thêm vào index.md
Xoá outline	Xoá file, cập nhật index.md, chạy coverage check nếu input đã convert
Đổi thứ tự	Rename file numbers, cập nhật index.md

Sau mỗi điều chỉnh, chạy coverage check (nếu input đã convert) để đảm bảo không bỏ sót.

planning-content