init-doc

name: init-doc description: Use when initializing a translation project from extraction through glossary, chapter mapping, and progress tracking. user-invocable: true disable-model-invocation: true

Initialize Document Translation

Overview

Initialize translation baseline from PDF extraction to chaptered docs, style decisions, glossary, and progress tracker.

Core principle: Build a deterministic, verifiable baseline before any large-scale translation.

Task Initialization (MANDATORY)

Before ANY action, create tasks using TaskCreate:

• One task per major phase (extraction, formatting, images/theme, terminology, chapter split, progress tracker)
• One task for final handoff gate

Interaction Rules

• All user interaction must be Traditional Chinese (zh-TW).
• AskUserQuestion prompts must be Traditional Chinese.
• Do not use Simplified Chinese in user-facing text.

The Process

Step 1: Cleanup and Source Validation

Run cleanup:

uv run python scripts/clean_sample_data.py --yes

Then resolve source PDF from $ARGUMENTS or ask user in Traditional Chinese. Ensure source is under data/pdfs/.

Before extraction, ask user in Traditional Chinese whether to preserve PDF images in the generated docs:

是否要保留 PDF 內的圖片，並在切分後的 Markdown 文件中保留對應圖片連結？

Record this decision as preserve_images: true/false for the rest of the run.

Verification: Source PDF exists under data/pdfs/; preserve_images decision recorded; cleanup script exited 0.

Step 2: Create Tasks

Create TaskCreate items for:

• extraction
• formatting decisions
• image retention decision
• image and theme setup
• terminology bootstrap
• chapter mapping
• progress tracker creation
• final handoff gate

Verification: All tasks created with correct descriptions; task list matches the phases above.

Step 3: Extract and Validate Raw Outputs

Run:

uv run python scripts/extract_pdf.py <pdf_path> --include-images

If preserve_images is false, run instead:

uv run python scripts/extract_pdf.py <pdf_path> --no-include-images

Validate outputs:

• data/markdown/<name>.md
• data/markdown/<name>_pages.md
• data/markdown/images/<name>/（only when preserve_images = true）

Verification: All expected output files exist and are non-empty.

Step 4: Cropping Review and Optional Split

Review readability and completeness. If needed, split large source into parts and re-extract until clean.

Verification: Extracted markdown is readable; no garbled text or truncated sections remain.

Step 5: Confirm Document Formatting Decisions

Summarize content to user in Traditional Chinese:

書本內容概覽：
- 主要內容類型：[規則說明、範例場景、角色選項...]
- 特殊結構：[大量表格、骰表、設計者備註...]
- 建議可使用的格式化元件：[...]

Collect formatting choices (Traditional Chinese):

• layout profile for extraction (auto / single-column / double-column)
• aside mapping (note/tip/caution/danger) — must include a mapping for game examples (game examples should always be rendered as asides)
• card/tabs usage
• table/dice-table conventions

Persist via script:

uv run python scripts/style_decisions.py init
uv run python scripts/style_decisions.py set-document-format \
  --layout-profile "<auto|single-column|double-column>" \
  --aside-note "<note_component>" \
  --aside-tip "<tip_component>" \
  --aside-caution "<caution_component>" \
  --aside-danger "<danger_component>" \
  --cards-usage "<cards_usage_note>" \
  --tabs-usage "<tabs_usage_note>" \
  --tables-convention "<table_note>" \
  --dice-tables-convention "<dice_table_note>"
uv run python scripts/validate_style_decisions.py

Ask user to choose translation mode in Traditional Chinese:

請選擇翻譯模式：
A. 純中文翻譯：完整翻譯所有內容，僅保留中文
B. 雙語模式：中文翻譯為主，英文原文以 blockquote 附於每段之後

Persist via:

uv run python scripts/style_decisions.py set-translation-mode \
  --mode "<full|bilingual>" \
  --reason "使用者在 init-doc 選擇翻譯模式"

Verification: style-decisions.json contains document_format section and translation_mode section; validate_style_decisions.py exits 0.

Step 6: Select Images, Theme, and Homepage Content

1. If preserve_images = true, ask user to assign extracted images for hero/background/og.
2. If preserve_images = true, copy and resize where needed.
3. If preserve_images = false, skip extracted image assignment and continue with theme-only setup.
4. Ask theme decisions in Traditional Chinese (mode/overlay/palette).
5. Update docs/src/styles/custom.css and persist style decisions.
6. Persist image retention decision via:

uv run python scripts/style_decisions.py set-images --preserve-images <true_or_false>

7. Ask for site meta in Traditional Chinese (all four fields):

   • 網站標題（site.title）：首頁 <title> 及 frontmatter title，例：「Rapscallion 遊戲規則」
   • 首頁描述（site.description）：SEO description，一句話
   • 副標語（site.tagline）：hero 區塊顯示的一行短語
   • 內容簡介（site.intro）：首頁「內容簡介」段落，一到兩句 Persist via:

   uv run python scripts/style_decisions.py set-site \
     --title "<USER_INPUT>" \
     --description "<USER_INPUT>" \
     --tagline "<USER_INPUT>" \
     --intro "<USER_INPUT>"
   

8. Ask for copyright and credits in Traditional Chinese:

   • Copyright notice text（例：© 2024 Author Name. All rights reserved.）
   • Credits entries as role → name pairs（例：原作者、翻譯、美術設計等）
   • Whether to show each section on the homepage

9. Persist via:

uv run python scripts/style_decisions.py set-copyright \
  --text "<USER_INPUT>" \
  --show-on-homepage <true_or_false>
uv run python scripts/style_decisions.py set-credits \
  --entry "原作者:..." \
  --entry "翻譯:..." \
  --show-on-homepage <true_or_false>

11. Ask whether there are any translation-wide notes the translator must always follow. Persist each note via:

uv run python scripts/style_decisions.py add-translation-note \
  --key "<short_key>" \
  --topic "<optional_topic>" \
  --note "<USER_INPUT>"

If the note is specific to one source file or future appended document, use:

uv run python scripts/style_decisions.py add-translation-note \
  --document-key "<pdf_stem_or_doc_id>" \
  --key "<short_key>" \
  --note "<USER_INPUT>"

12. Run:

uv run python scripts/validate_style_decisions.py

generate_nav.py will render these as ## 版權宣告 and ## 製作名單 sections on the homepage. If neither is provided, a generic fallback disclaimer is used.

Verification: validate_style_decisions.py exits 0; style-decisions.json contains site meta, copyright, credits, and image decisions.

Step 7: Build Terminology Baseline

Invoke term-decision skill for terminology bootstrap instead of duplicating the workflow here.

Required handoff to term-decision:

1. Source is the extracted markdown from this init run.
2. First inspect high-signal terminology sources in the original book:
   • source glossary / terminology pages
   • index pages
   • appendix term lists
   • playbook / move summary tables that clearly define recurring mechanics terms
3. Complete one first-pass terminology bootstrap from those sections:
   • prefill obvious term translations into glossary.json
   • keep wording consistent with style-decisions.json
   • ask the user only about uncertain, culturally nuanced, or mechanics-ambiguous terms
4. After that first pass, generate and verify the remaining candidates with:

uv run python scripts/term_generate.py --min-frequency 2
uv run python scripts/term_cal_batch.py
uv run python scripts/validate_glossary.py
uv run python scripts/term_read.py --fail-on-missing --fail-on-forbidden

init-doc must not continue to chapter split until the term-decision handoff completes cleanly.

Verification: validate_glossary.py and term_read.py --fail-on-missing --fail-on-forbidden both exit 0.

Step 8: Chapter Split and Navigation

Invoke chapter-split skill instead of duplicating split logic here.

Required handoff to chapter-split:

1. Source is the extracted _pages.md file from this init run.
2. Reuse the preserve_images decision from Step 1.
3. Reuse the formatting and terminology decisions already completed in Steps 5-7.
4. Generate chapters.json, split docs output, and regenerate navigation.
5. If chapter-split reports unresolved critical issues, stop init-doc and resolve them before continuing.

Verification: chapters.json exists; split docs generated; nav regenerated.

Step 9: Create Translation Progress Tracker

Create data/translation-progress.json from chapters.json:

uv run python scripts/init_create_progress.py --force

Tracker contract:

• chapter ids derived from output file paths
• source page ranges mapped from chapter config
• initial status not_started
• _meta fields (updated, total_chapters, completed)

Verification: data/translation-progress.json exists; contains all chapters from chapters.json with status not_started; _meta fields present.

Step 10: Final Gate and Handoff (Fail-Closed)

Run one-shot handoff gate:

uv run python scripts/init_handoff_gate.py

If any gate fails, stop and fix before completion.

Verification: init_handoff_gate.py exits 0; all tasks marked completed.

Flowchart

digraph init_doc {
    rankdir=TB;
    cleanup [label="Cleanup &\nsource validation", shape=box];
    tasks [label="Create tasks", shape=box];
    extract [label="Extract PDF", shape=box];
    img_decision [label="Preserve\nimages?", shape=diamond];
    extract_img [label="Extract with\n--include-images", shape=box];
    extract_noimg [label="Extract with\n--no-include-images", shape=box];
    crop [label="Cropping review\n& optional split", shape=box];
    format [label="Formatting\ndecisions", shape=box];
    theme [label="Images, theme\n& homepage", shape=box];
    term [label="Terminology\nbaseline\n(term-decision)", shape=box];
    term_ok [label="Term validation\npasses?", shape=diamond];
    split [label="Chapter split\n(chapter-split)", shape=box];
    split_ok [label="Split\nsucceeded?", shape=diamond];
    progress [label="Create progress\ntracker", shape=box];
    gate [label="Final handoff\ngate", shape=box];
    gate_ok [label="Gate\npasses?", shape=diamond];
    done [label="Done →\ntranslate", shape=box];
    fix [label="Fix & retry", shape=box];

    cleanup -> tasks -> extract;
    extract -> img_decision;
    img_decision -> extract_img [label="yes"];
    img_decision -> extract_noimg [label="no"];
    extract_img -> crop;
    extract_noimg -> crop;
    crop -> format -> theme -> term;
    term -> term_ok;
    term_ok -> split [label="yes"];
    term_ok -> fix [label="no"];
    fix -> term;
    split -> split_ok;
    split_ok -> progress [label="yes"];
    split_ok -> fix [label="no"];
    progress -> gate;
    gate -> gate_ok;
    gate_ok -> done [label="yes"];
    gate_ok -> fix [label="no"];
}

Progress Sync Contract (Required)

1. Keep tasks updated via TaskUpdate at every step.
2. Mark blockers immediately and include failing command/context.
3. Close tasks only after final gate passes.

When to Stop and Ask for Help

Stop when:

• source extraction repeatedly fails
• chapter-split cannot produce a usable config
• glossary validation cannot be resolved safely
• docs build fails with unclear root cause

When to Revisit Earlier Steps

Return to earlier steps when:

• user changes formatting/theme policy
• user changes proper noun strategy
• source markdown changes enough to invalidate page mapping

Red Flags

Next Step

If style-decisions.json has translation_mode.mode == "bilingual", continue with /bilingual-translate. Otherwise, continue with /translate or /super-translate.

Example Usage

/init-doc
/init-doc data/pdfs/rulebook.pdf