webnovel-review

Quality Review Skill

Goals

• Resolve the real book project root, dispatch the unified reviewer to complete the structured review and persist it to the database.
• Main-chain facts are based on .story-system/reviews/chapter_{NNN}.review.json and the latest accepted CHAPTER_COMMIT ;.webnovel/state.json is only a compatibility projection.
• If there are blocking=true issues, hand them to the user for a decision.

Red Lines

• Must pass the Agent tool call to reviewer; the main flow is forbidden from fabricating conclusions or substituting an oral summary for subagent output.
• The reviewer returns only strict JSON; the main flow is responsible for writing the return value to ${PROJECT_ROOT}/.webnovel/tmp/review_results.json, and then review-pipeline overwrites it as the standard review_result artifact.
• The report and metrics are produced only by review-pipeline --save-metrics ; the main flow does not fabricate overall_score。
• Invalid project root / missing .webnovel/state.json / missing body to be reviewed → block.

Execution Flow

Step 1: Resolve the project root

export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"

PROJECT_ROOT must contain .webnovel/state.json, otherwise block.

Step 2: If the target chapter lacks a contract, refresh the runtime contract

When the target chapter lacks a runtime contract, first refresh it with the real goals for this chapter from the detailed outline (CHAPTER_GOAL forbids {章纲目标} / 第N章章纲目标 placeholder text):

GENRE="$(python -X utf8 -c "import json; s=json.load(open('${PROJECT_ROOT}/.webnovel/state.json',encoding='utf-8')); pi=s.get('project_info',{}); print(pi.get('genre') or s.get('project',{}).get('genre',''))")"

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
  story-system "${CHAPTER_GOAL}" --genre "${GENRE}" --chapter {chapter_num} --persist --emit-runtime-contracts --format both

Step 3: Load references as needed

Trigger	Reference
always	../../references/shared/core-constraints.md
always	../../references/review-schema.md
Review involves excitement points or hooks	../../references/shared/cool-points-guide.md
Review involves multi-thread interweaving	../../references/shared/strand-weave-pattern.md
blocking issue requires user decision (Step 8)	../../references/review/blocking-override-guidelines.md

Step 4: Load projection state and the body to be reviewed

cat "${PROJECT_ROOT}/.webnovel/state.json"

Confirm the current chapter number and the corresponding body file; if the body or the compatibility state file is missing, block immediately.

Step 5: Call the unified review Agent

Must pass the Agent tool call to reviewer. The review methods and dimension details are built into the reviewer; this Skill does not expand on them.

Use the Agent tool to run `webnovel-writer:reviewer`.

Prompt: chapter={chapter_num}; chapter_file={chapter_file}; project_root=${PROJECT_ROOT}; scripts_dir=${SCRIPTS_DIR}。严格输出 reviewer schema JSON，不评分，不口头总结。

After the reviewer returns, the main flow writes the strict JSON to ${PROJECT_ROOT}/.webnovel/tmp/review_results.json(the reviewer does not hold Write and is a non-writer of this artifact).review-pipeline must overwrite the same path as the standard review_result artifact (including blocking_count）。

After the call, the main flow must record the SubagentRun summary (only for the final report):

{
  "name": "reviewer",
  "user_label": "写作检查",
  "status": "completed | partial | failed | skipped",
  "problems": [],
  "auto_handled": [],
  "needs_user_action": false,
  "duration_ms": 0,
  "outputs": []
}

If the reviewer skips, fails, produces incomplete output, has an empty body, skips dimensions, has a blocking issue, or has abnormal duration, it must write to problems / auto_handled, and must not be silent in the final report.

Step 6: Generate the report and persist it to the database

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" review-pipeline \
  --chapter {chapter_num} \
  --review-results "${PROJECT_ROOT}/.webnovel/tmp/review_results.json" \
  --metrics-out "${PROJECT_ROOT}/.webnovel/tmp/review_metrics.json" \
  --report-file "审查报告/第{chapter_num}章审查报告.md" \
  --save-metrics

review-pipeline --save-metrics simultaneously completes report generation,review_metrics.json output,review_metrics table writes. The blocking determination is based on the blocking=true in review_results.

Step 7: Write the compatibility review record

python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" update-state -- --add-review "{chapter_num}-{chapter_num}" "审查报告/第{chapter_num}章审查报告.md"

Compatibility projection / read model, not the post-write source of truth.

Step 8: Handle blocking

When any blocking=true issue exists, use AskUserQuestion to let the user decide:

• Fix immediately: output a rework list, and make only minimal changes with the user's explicit authorization.
• Save the report only, handle later: keep the report and metric records, and end the flow.

Success Criteria

1. The real book project root has been resolved.
2. A structured issue JSON has been output via reviewer and written to disk at .webnovel/tmp/review_results.json。
3. The review report has been generated,review_metrics has been written to index.db，review_metrics.json has been output.
4. The review record has been written to the .webnovel/state.json compatibility projection.
5. When a blocking issue exists, the user has explicitly chosen a handling strategy.

Author-friendly process prompts and recovery contract

Before the review starts, first explain what this session will go through: locate the text to be reviewed -> refresh missing contracts -> writing check -> generate report and metrics -> handle blocking decisions. Process prompts use the author's language and do not directly output raw JSON, traceback, or long command logs; technical details are written to .webnovel/logs/run_last.log：

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" run-log \
  --event review-progress \
  --payload-json "{\"stage\": \"review\", \"chapter\": {chapter_num}}" \
  --format text

Each process prompt must be no more than two lines, stating only the current action and its impact, for example "Generating review report: will put blocking issues and the most worthwhile suggestions at the top." Minimize interruptions for confirmation strategy: do not ask when there is no blocking; ask only when there is a blocking issue, the text to be reviewed is missing, or the user requests whether to modify immediately.

When user adjudication is needed, use limited options and explain the impact; for example, fix immediately / save the report only and handle later / abandon this review. When stuck, must explain the blocker, what has been completed, and recovery suggestions, for example "reviewer results have been saved, metrics failed to persist; rerunning /webnovel-review {chapter_num} will continue from report persistence."

Only for unrecoverable failures, indicate in the final report .webnovel/logs/run_last.log; otherwise only keep logs and do not disturb the author. At the end, must call the author report helper:

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" user-report \
  --stage review \
  --chapter {chapter_num} \
  --format text

Author-friendly final report contract

The final reply must be author-facing and must not output raw JSON, traceback, or long command logs. Use a fixed three-part structure and begin with a one-sentence overall status:

总状态：已完成 / 部分完成 / 需要你处理 / 未完成。

一、产生的文件与完成情况
- ...

二、过程中遇到的问题与异常耗时
- 已自动处理：...
- 建议确认：...
- 必须处理：...

三、下一步建议
- ...

Must report:

• Review report file.
• .webnovel/tmp/review_results.json。
• .webnovel/tmp/review_metrics.json。
• review_metrics whether it was persisted.
• Number of blocking issues.
• User adjudication status.
• If there is no blocking, clearly state that writing can continue.

Status rules:

• When there is a blocking issue and the user has not chosen a handling strategy, the final status is "needs your handling."
• When only saving the report and handling later, the final status is "needs your handling" or "partially complete."
• When the reviewer is skipped, fails, or outputs incompletely, the final status must not say "completed."

Exception classification:

• Automatically handled: duplicate report generation, overwriting this session's old review intermediate files, successfully supplementing metrics.
• Suggested confirmation: non-blocking but high-value revision suggestions, naming or setting detail suggestions worth a look.
• Must handle: blocking issue, missing text to be reviewed, incomplete reviewer output, metrics persistence failure.

Next-step suggestions must use task-oriented language + copyable commands, for example:

- 审查无阻断，可以继续写下一章：
  /webnovel-write {next_chapter}

Do not write token statistics; if troubleshooting is needed, only provide the log path or suggest running /webnovel-doctor。