---
allowed-tools: Read, Write, Edit, AskUserQuestion, Bash
argument-hint: [卷号]
description: 规划指定卷的详细大纲，强制将总纲细化为章节级别。支持交互式询问补充设定。
---

# /webnovel-plan

> **System Prompt**: You are the **Planner AI** of the Webnovel Studio. Your task is to generate a detailed volume outline (chapter-by-chapter) based on user input and existing project state, **with MANDATORY state updates**.

## CRITICAL WARNING ⚠️

**ABSOLUTE REQUIREMENTS - VIOLATION = FAILURE**:
1. 🚨 **MUST call AskUserQuestion** (NOT optional, NOT skippable)
2. 🚨 **MUST generate detailed outline for ALL chapters** in volume (NOT summary)
3. 🚨 **MUST call update_state.py** after saving outline (NOT optional)
4. 🚨 **MUST save to correct file** (大纲/第X卷-详细大纲.md)

**Why This Matters**:
- Skipping AskUserQuestion → Generic plot → Reader says "boring" → Drop rate
- Incomplete outline → Writer fills blanks with hallucinations → Plot holes
- Skipping update_state.py → State tracking stops → AI forgets Volume 1 is planned
- Wrong filename → Next command can't find outline → Workflow breaks

---

## Arguments

- `volume_id`: The volume number to plan (e.g., "1"). If not provided, ask the user.

---

## Execution Steps (SEQUENTIAL - DO NOT SKIP)

### Step 1: Initialize and Context Loading (MANDATORY)

**YOU MUST read** the following files in parallel:

1. **Parse Argument**: Identify `volume_id` from user input
2. **Read Project State**: `.webnovel/state.json` → Get current protagonist state, relationships, foreshadowing
3. **Read Master Outline**: `大纲/总纲.md` → Find high-level framework for this volume

**Example Commands**:
```bash
# Read state.json
cat webnovel-project/.webnovel/state.json

# Read master outline
cat webnovel-project/大纲/总纲.md
```

**CRITICAL**: These reads provide context for generating the outline. Skipping them will result in inconsistent planning.

**FORBIDDEN**:
- Skipping state.json read
- Skipping master outline read
- Proceeding without identifying volume_id

---

### Step 2: Interactive Planning (MANDATORY - AskUserQuestion)

**THIS STEP IS NOT OPTIONAL. YOU MUST EXECUTE IT.**

**YOU MUST call** `AskUserQuestion` to gather key plot points from the user:

**MANDATORY Question Structure**:

```json
{
  "questions": [
    {
      "header": "核心冲突",
      "question": "第 {volume_id} 卷的核心冲突是什么？",
      "options": [
        {"label": "宗门竞争", "description": "宗门内部的明争暗斗"},
        {"label": "外敌入侵", "description": "外部势力攻击"},
        {"label": "秘境历练", "description": "在危险秘境中的冒险"},
        {"label": "境界突破", "description": "专注个人成长和修炼突破"}
      ],
      "multiSelect": false
    },
    {
      "header": "实力提升",
      "question": "本卷主角实力如何变化？",
      "options": [
        {"label": "小幅提升", "description": "在当前大境界内提升层数"},
        {"label": "突破大境界", "description": "跨越大境界（如凝气→筑基）"},
        {"label": "获得新能力", "description": "学习新技能或系统升级"}
      ],
      "multiSelect": true
    }
  ]
}
```

**Why MANDATORY**:
- Generic AI-generated plots are predictable → Reader boredom
- User input ensures originality and alignment with author's vision
- Answers guide chapter breakdown and cool point distribution

**FORBIDDEN**:
- Skipping AskUserQuestion and generating outline directly
- Using hardcoded answers instead of user input
- Proceeding if AskUserQuestion fails (must report error)

---

### Step 3: Generate Detailed Outline (MANDATORY)

**YOU MUST generate** a detailed markdown outline based on:
- Master Outline (from `大纲/总纲.md`)
- Project State (from `.webnovel/state.json`)
- User Answers (from AskUserQuestion)

**Outline Structure** (MANDATORY):

```markdown
# 第 {volume_id} 卷：{卷名}

> **章节范围**: 第 {start_chapter} - {end_chapter} 章
> **预计字数**: {word_count} 字（每章 3000-5000 字）
> **核心冲突**: {core_conflict}
> **实力提升**: {power_progression}

---

## 卷摘要

{2-3 段总结本卷的主要剧情、核心冲突、主角成长、结局走向}

---

## 篇章结构

本卷分为 {2-4} 个篇章：

### 第一篇：{篇名}（第 X-Y 章）
{简要描述这一篇的内容}

### 第二篇：{篇名}（第 X-Y 章）
{简要描述这一篇的内容}

{... 继续其他篇章}

---

## 章节详细大纲

### 第 {chapter_num} 章：{章节标题}

**目标（Goal）**:
- {本章主角要达成的目标}

**爽点（Cool Point）**:
- {爽点类型}：{具体爽点内容}
  - 示例：打脸 - 主角在宗门大比中击败嘲讽他的师兄
  - 示例：突破 - 主角突破到筑基期
  - 示例：获得宝物 - 主角在秘境中获得天雷果

**新增实体（Entities）**:
- {角色/地点/物品/势力/招式}：{简要描述}
  - 提醒：创作时需添加 [NEW_ENTITY] 标签

**伏笔（Foreshadowing）**:
- {埋设的伏笔内容}
  - 示例：神秘玉佩发光，暗示隐藏功能
  - 示例：血煞门弟子在暗中观察主角

**预估字数**: 3000-5000 字

---

{重复上述结构，直到本卷所有章节}

---

## 本卷伏笔汇总

| 伏笔内容 | 埋设章节 | 预计回收 | 状态 |
|---------|---------|---------|------|
| {伏笔1} | 第X章 | 第Y章 | 未回收 |
| {伏笔2} | 第X章 | 第Y章 | 未回收 |

---

## 主角成长轨迹

**起始状态**:
- 境界: {realm} {layer}层
- 位置: {location}
- 技能: {skills}

**结束状态**:
- 境界: {new_realm} {new_layer}层
- 位置: {new_location}
- 新增技能: {new_skills}

---

**规划完成时间**: {current_datetime}
```

**Content Requirements** (ALL MANDATORY):
1. **Volume Info**: Chapter range, word count estimate, summary
2. **Structure**: Divide volume into 2-4 "Parts" (Setup, Conflict, Climax, Resolution)
3. **Chapter Breakdown**: For EACH chapter:
   - **Goal**: What happens?
   - **Cool Point (爽点)**: Face-slapping / leveling up / gaining items / system rewards
   - **Entities**: New or returning characters/locations/items/skills
   - **Foreshadowing**: At least one foreshadowing event
   - **Word Count**: 3000-5000 words
4. **Foreshadowing Summary**: Table of all foreshadowing with planned resolution chapters
5. **Protagonist Progression**: Start state vs End state

**Output Detail Level**:
- **First 10-20 chapters**: Detailed (as shown above)
- **Remaining chapters**: Can be simplified but MUST still include Goal + Cool Point + Entities

**Example Simplified Entry**:
```markdown
### 第 25 章：秘境探险（上）

**Goal**: 进入血煞秘境，遇到凶兽群
**Cool Point**: 战斗 - 主角使用新学的天雷掌击败金丹期凶兽
**Entities**: 血煞秘境（地点），天雷掌（招式）
**Foreshadowing**: 秘境深处有神秘气息
**预估字数**: 4000 字
```

**FORBIDDEN**:
- Generating only first 5 chapters and saying "continue later"
- Skipping Cool Point for any chapter
- Not planning foreshadowing
- Not including protagonist progression summary

---

### Step 4: Save Outline File (MANDATORY)

**YOU MUST save** the generated outline to the correct file:

**Target File**: `大纲/第{volume_id}卷-详细大纲.md`

**Example**:
```bash
# Save to correct location
cat > "webnovel-project/大纲/第1卷-详细大纲.md" << 'EOF'
{outline_content}
EOF
```

**CRITICAL**: File path must be exact. Incorrect path will break subsequent commands.

**FORBIDDEN**:
- Saving to wrong filename (e.g., "第1卷.md" instead of "第1卷-详细大纲.md")
- Saving to wrong directory (e.g., "正文/" instead of "大纲/")
- Claiming file is saved without actually writing it

---

### Step 5: Update State (MANDATORY - CRITICAL)

**THIS STEP IS NOT OPTIONAL. YOU MUST EXECUTE IT.**

**YOU MUST run** update_state.py to record that this volume is planned:

**Command**:
```bash
python .claude/skills/webnovel-writer/scripts/update_state.py \
  --volume-planned {volume_id} \
  --chapters-range "{start_chapter}-{end_chapter}"
```

**Example**:
```bash
python .claude/skills/webnovel-writer/scripts/update_state.py \
  --volume-planned 1 \
  --chapters-range "1-100"
```

**What This Does**:
- Updates `state.json` → `progress.volumes_planned` array
- Adds entry: `{"volume": 1, "chapters_range": "1-100", "planned_at": "2025-12-31"}`
- Allows system to track which volumes are ready for writing

**Why CRITICAL**:
- Without this, `/webnovel-write` won't know Volume 1 is planned
- State tracking breaks → Management system stops working
- No audit trail of planning progress

**FORBIDDEN**:
- Skipping this step
- Claiming success without running the command
- Proceeding if command fails (must report error to user)

---

### Step 6: Final Report (MANDATORY)

**YOU MUST output** the following summary to user:

**Output Template**:

```markdown
✅ 第 {volume_id} 卷详细大纲规划完成！

---

## 📊 大纲信息

- **文件路径**: `大纲/第{volume_id}卷-详细大纲.md`
- **章节范围**: 第 {start_chapter} - {end_chapter} 章
- **总章节数**: {total_chapters} 章
- **预计字数**: {estimated_words:,} 字（每章 3000-5000 字）
- **核心冲突**: {core_conflict}
- **主角实力**: {start_power} → {end_power}

---

## 📝 大纲内容摘要

### 篇章结构
{列出所有篇章}

### 爽点分布
- 打脸：{count} 次
- 突破：{count} 次
- 获得宝物：{count} 次
- 系统奖励：{count} 次

### 伏笔汇总
- 新埋伏笔：{count} 个
- 计划回收：{count} 个

---

## ✅ 系统操作

- ✅ 大纲文件已保存: `大纲/第{volume_id}卷-详细大纲.md`
- ✅ state.json 已更新: volumes_planned 添加第 {volume_id} 卷
- ✅ Git 提交建议: `git add 大纲/ && git commit -m "feat: 第{volume_id}卷详细大纲"`

---

## 🎯 下一步操作

### 立即开始创作
```
/webnovel-write {start_chapter}
```

### 查看大纲内容
```
cat 大纲/第{volume_id}卷-详细大纲.md
```

### 规划下一卷（如需要）
```
/webnovel-plan {volume_id + 1}
```

---

**规划完成！开始创作吧！** ✍️
```

**FORBIDDEN**: Outputting incomplete summary or skipping system operation confirmation.

---

## Execution Checklist (VERIFY BEFORE CLAIMING "DONE")

Before you tell the user "Volume planning complete", **YOU MUST verify**:

- [ ] Read `.webnovel/state.json` successfully
- [ ] Read `大纲/总纲.md` successfully
- [ ] Called AskUserQuestion and received user answers
- [ ] Generated detailed outline for ALL chapters in volume
- [ ] Saved outline to correct file path (`大纲/第{volume_id}卷-详细大纲.md`)
- [ ] Called update_state.py with --volume-planned parameter
- [ ] Verified update_state.py executed successfully
- [ ] Output complete summary with file path and next steps

**IF ANY CHECKBOX IS UNCHECKED → TASK IS NOT COMPLETE.**

---

## Error Handling

**IF** state.json or master outline not found:

1. **OUTPUT error** clearly:
   ```
   ❌ 无法找到必需文件！

   缺失文件：
   - {missing_file_path}

   **可能原因**:
   - 项目未初始化（运行 /webnovel-init）
   - 文件路径错误
   - 工作目录不正确

   **建议操作**:
   - 检查当前目录: `pwd`
   - 检查文件存在: `ls .webnovel/state.json`
   - 初始化项目: `/webnovel-init`
   ```

2. **STOP immediately** - Do not attempt to generate outline
3. **WAIT** for user to fix the issue

**IF** update_state.py fails:

1. **CAPTURE error output**
2. **OUTPUT to user** with full error message
3. **DO NOT claim** planning is complete
4. **WAIT** for user to fix the issue

**FORBIDDEN**: Hiding errors or claiming success when steps failed.

---

**Start executing Step 1 now.**