wa-convert

Glob("**/writer-agent/scripts/wa-convert")

SCRIPTS_DIR = directory chứa wa-convert  (ví dụ: /Users/x/.claude/skills/writer-agent/scripts)
SKILL_DIR   = parent của SCRIPTS_DIR     (ví dụ: /Users/x/.claude/skills/writer-agent)
VOICES_DIR  = SKILL_DIR/voices           (ví dụ: /Users/x/.claude/skills/writer-agent/voices)
STRUCTURES_DIR = SKILL_DIR/structures    (ví dụ: /Users/x/.claude/skills/writer-agent/structures)
IDENTITIES_DIR = SKILL_DIR/identities    (ví dụ: /Users/x/.claude/skills/writer-agent/identities)
AUDIENCES_DIR  = SKILL_DIR/audiences     (ví dụ: /Users/x/.claude/skills/writer-agent/audiences)
EMOTIONS_DIR   = SKILL_DIR/emotional_maps (ví dụ: /Users/x/.claude/skills/writer-agent/emotional_maps)

/Users/x/.claude/skills/writer-agent/scripts/wa-convert

• Gọi convert:

  /Users/x/.claude/skills/writer-agent/scripts/wa-convert file.pdf

• Đọc voice:

  /Users/x/.claude/skills/writer-agent/voices/teacher.md

• Đọc structure:

  /Users/x/.claude/skills/writer-agent/structures/building-blocks.md

• Đọc identity:

  /Users/x/.claude/skills/writer-agent/identities/tech-builder.md

QUAN TRỌNG: KHÔNG BAO GIỜ hardcode

.claude/skills/writer-agent/...

, luôn dùng đường dẫn tuyệt đối từ Glob.

1. Read content (if file)
2. Rewrite to structured markdown (add headings, preserve content)
3. Propose title
4. Execute:

echo "{rewritten_content}" | {SCRIPTS_DIR}/wa-paste-text - --title "{title}"

📖 See:

references/_dimension-comparison.md

for full default mapping table, compatibility matrix, and mixing guidelines.

_dimension-comparison.md

1. **target_ratio**

   : Controls total article length relative to source

• Standard level: 30-40% (midpoint 35%)
• This ratio applies to the entire article wordcount

1. **example_percentage**

   : Controls retention of examples within kept content

• Standard level: 60% of examples
• This percentage applies only to example sections

See detail-levels.md for worked examples and full specification.

• Direct Path conditions are checked FIRST and override tier boundaries
• Documents 20K-50K with ≤3 articles use Direct Path (not Tier 1)
• Only documents failing Direct Path conditions fall through to tier selection

Note: Direct Path

<50K

condition is further limited by language: EN ~44K, VI ~32K, mixed ~38K words. These limits are pre-computed in

structure.json → direct_path.capacity_ok

. If capacity exceeded, fallback to Tier 1.

• Direct Path: Main agent handles everything (no subagents)
• Tier 1: Lightweight subagents, read source via line ranges
• Tier 2: Context extraction for compression (only tier with separate glossary file)
• Tier 3: Like Tier 1 but larger chunks, more selective glossary, lower concurrency

structure.json

direct_path

wa-convert

structure.json → direct_path.eligible?
├─ YES AND direct_path.capacity_ok?
│   └─ DIRECT PATH
│       └─ Skip context extraction
│       └─ Main agent writes ALL articles
│       └─ ~30% faster for small documents
│
├─ YES BUT NOT direct_path.capacity_ok?
│   └─ WARN: direct_path.warning
│   └─ RECOMMEND: Use Tier 1 with subagents instead
│
├─ NO AND tier_recommendation.tier <= 2?
│   └─ STANDARD PATH (3.1-3.5)
│
└─ NO AND tier_recommendation.tier == 3?
    └─ FAST PATH (Tier 3)

Note:

direct_path

fields in structure.json (since v1.2) include

eligible

,

capacity_ok

,

capacity_limit

, and

warning

. These are pre-computed based on word count, estimated article count, and detected language. Main agent does NOT need to recalculate these values.

Note: Direct Path capacity limit depends on language: EN ~44K, VI ~32K, mixed ~38K words. Use

structure.json → language

field for accurate limit.

📖 READ FIRST: context-optimization.md explains anti-patterns that waste 50%+ context budget. Review before proceeding.

structure.json

• ONLY read

  structure.json

  for outline, stats, tier recommendation
• DO NOT read

  content.md

  - it wastes context budget
• Skip manual scanning (outline already in JSON)

structure.json

wa-convert

structure.json

undefined

Group sections into articles (default 3-7, or user-specified count):

```markdown
| #   | Slug  | Title         | Sections      | Est. Words | Reading Time |
| --- | ----- | ------------- | ------------- | ---------- | ------------ |
| 1   | intro | Introduction  | S01, S02      | 2000       | ~13 min      |
| 2   | core  | Core Concepts | S03, S04, S05 | 2500       | ~13-15 min   |

• All sections must be mapped. Coverage check at end.
• Target reading time phụ thuộc detail level: Concise ~5min, Standard ~10min, Comprehensive ~13min, Faithful ~15min
• Target words/bài: 2000-3000 từ (tham khảo, không bắt buộc)
• Nếu user chỉ định số bài → tuân theo, không auto-split thêm

content_type

tutorial

conceptual

narrative

analysis

mixed

CONTENT_TYPE: {type}

_plan.md

undefined

1. User-specified count: Nếu user yêu cầu số bài cụ thể → tuân theo, KHÔNG auto-split
2. Auto-split: Chỉ áp dụng khi user KHÔNG yêu cầu số bài cụ thể

• MAX_OUTPUT_WORDS = 3000

  (~15 min reading time)

• TARGET_PART_WORDS = 2000

  (~13 min reading time)
• Atomic unit = H2 block (H2 + H3 children). NEVER split within paragraph, H3, or critical section.

estimated_output = source_words × detail_ratio > MAX_OUTPUT_WORDS

{SCRIPTS_DIR}/wa-validate-split docs/generated/{book}/analysis/_plan.md

02-core.md

02-core-part1.md

02-core-part2.md

• Tier 1 (<50K words): Subagents read source directly via line ranges
• Tier 3 (>=100K words): Subagents read source directly via line ranges
• Direct Path (<20K words): Main agent writes directly

• Tier 1/3 or <20K words: Skip context files (subagents read source directly via line ranges)
• Tier 2 (50K-100K): Spawn context extractor subagents (batch: min(3, article_count))
• Template:

  templates/_context-file-template.md

analysis/XX-{slug}-context.md

• All sections have IDs (from structure.json)
• Critical sections marked (* auto-detected in structure.json)
  • Guideline: Thường <=30% sections là critical
  • If >30%: Tự động ghi nhận trong

    _plan.md

    , KHÔNG cần user confirmation
    • Document: "High critical ratio: {ratio}% - technical content"
    • Tiếp tục workflow bình thường
  • If >50%: Tự động chuyển sang Tier 3 strategy (read source directly)
    • KHÔNG cần STOP hoặc ask user
    • Tier 3 xử lý được high critical ratio vì đọc source trực tiếp
    • Ghi log: "Auto-escalated to Tier 3 due to high critical ratio"
  • Rationale: Tự động xử lý thay vì blocking workflow để hỏi user
• Article plan covers 100% sections
• For Tier 3: _plan.md created with line ranges

1. CONTEXT RULES - Đã embed trong prompt template, cấm subagent glob/read files thừa
2. run_in_background: true - Dùng cho parallel article writing (≥3 articles). Main agent không nhận full transcript vào context, chỉ check output file khi cần.

undefined

00-overview.md

• Requires full series knowledge
• Template:

  templates/_overview-template.md

• Target: 300-400 words (initial)
• Include placeholders for Key Takeaways and Article Index

• Surprising insight + Micro-story + Core questions + Why It Matters
• Placeholder sections for Điểm chính and Mục lục

• Đọc voice file + structure file
• Đọc source content.md trực tiếp (full hoặc theo line ranges từ structure.json)
• Apply tất cả shared rules: LANGUAGE, FORMATTING, REWRITE RULE, ANTI-AI WRITING
• KHÔNG cần return format (vì không có subagent)
• Viết từng article theo

  _plan.md

  , save vào

  articles/XX-{slug}.md

• Mỗi article MUST end with "## Các bài viết trong series"
• Coverage tracking: main agent tự tạo

  _coverage.md

  sau khi viết xong tất cả

Task tool:
- subagent_type: "general-purpose"
- description: "Write: {title}"
- run_in_background: true  # Dùng cho ≥3 articles
- prompt: [Use references/article-writer-prompt.md]

1. Spawn 02-core-part1.md
2. Wait for completion → extract context bridge
3. Spawn 02-core-part2.md (with context from part1)
4. Wait → extract context bridge
5. Spawn 02-core-part3.md (with context from part2)

**Context bridge extraction:**

> See [large-doc-processing.md §Context Bridge](references/large-doc-processing.md#context-bridge) for the `extract_context_bridge()` function used between multi-part articles.

**Prompt validation (optional, for debugging):**

```bash
echo "{prompt_text}" | {SCRIPTS_DIR}/wa-validate-prompt --tier {1|2|3} --stdin

• Tier 1-2:

  max_concurrent = 3

  (smaller chunks ~3.5K words)
• Tier 3:

  max_concurrent = 2

  (larger chunks ~10K words)
• Dynamic adjustment: large chunks (>8K) → reduce to 2, all small (<2K) → increase to 5
• On any completion → spawn next immediately (no batch waiting)
• Benefits: 25-35% faster than static batching

• Format:

  "Writing articles: {completed}/{total} completed"

• Example:

  "Writing articles: 3/7 completed"

• Do NOT include time estimates

Section | Status

Section | Assigned To | Used In | Status

_coverage.md

DONE: {filename} | {N} words
KEY_TAKEAWAY: Sinh lực bùng lên khi có mục đích rõ ràng và hành động mỗi ngày
COVERAGE:
| Section | Status |
|---------|--------|
| S01 | ✅ quoted |
| S02 ⭐ | ✅ faithful |
RESULT: PASS
SERIES_LIST: YES
VERIFY: "Vita Nova" (L21)

• PASS: Tất cả assigned sections được covered HOẶC skipped với lý do hợp lệ (redundant, off-topic, user instruction)
• FAIL: Có section bị missing hoặc skipped không hợp lệ (không có lý do, hoặc "too long" / "already covered" thiếu reference)
• Word count: Chỉ thống kê, KHÔNG ảnh hưởng PASS/FAIL

_coverage.md

• Giữ 100% ý nghĩa và thông tin gốc, KHÔNG được tóm tắt hay lược bỏ
• PHẢI viết lại bằng tiếng Việt theo voice đã chọn
• KHÔNG copy nguyên văn từ source
• If unable to include fully → flag for review

• All articles written (check pending list vs DONE returns)
• All RESULT: PASS (coverage đầy đủ)
• All SERIES_LIST: YES
• KEY_TAKEAWAY collected từ mỗi subagent (dùng cho Step 5.1)
• VERIFY quotes provided (spot-check source fidelity)

1. [Concept từ article 1 KEY_TAKEAWAY]: [Expand từ takeaway]
2. [Concept từ article 2 KEY_TAKEAWAY]: [Expand từ takeaway]
3. [Concept từ article 3 KEY_TAKEAWAY]: [Expand từ takeaway]

**Các bài viết trong series** (Series List) - compose từ `_plan.md`:

```markdown

1. Tổng quan - Brief description (đang xem)
2. Article 1 Title - Brief description
3. Article 2 Title - Brief description

**Final overview target**: 400-600 words (overview đặc biệt, dùng word target thay vì section coverage)

**Fallback nếu KEY_TAKEAWAY kém**: Nếu takeaway quá generic hoặc trống, dùng article title + plan description từ `_plan.md` thay thế. KHÔNG đọc article file chỉ để cải thiện takeaway.

• Total: {N} | Used: {N} | Missing: {N}

**Edge cases** (reassignment, shared sections, skipped): See [large-doc-processing.md#coverage-tracking](references/large-doc-processing.md#coverage-tracking).

Run validation:

```bash
{SCRIPTS_DIR}/wa-validate docs/generated/{book}/analysis/_coverage.md

• All RESULT: PASS (từ subagent returns)
• Overview updated with Key Takeaways and Series List (đọc

  00-overview.md

  ~600 words)
• All SERIES_LIST: YES (từ returns, append nếu NO)
• All links in series lists verified (trong overview file)
• _coverage.md reported (>=95% target, >=90% acceptable)
• Critical ⭐ sections: VERIFY quotes match source (spot-check từ returns)
• Warnings logged for any skipped sections
• Anti-AI writing rules passed (xem article-writer-prompt.md#anti-ai-writing)

Policy: Không tự động retry. Mọi lỗi đều report cho user và chờ quyết định. See retry-workflow.md.