sunrain520/spec-first/spec-doc-review

Document Review

Review requirements or plan documents through multi-persona analysis. Task packs are reviewed as derived, report-only execution inputs against their current source plan. Dispatches generic subagents seeded with skill-local reviewer prompt assets, applies safe_auto fixes only when the run-local mutation policy is markdown-write, and preserves the same structural/semantic review as report-only findings when mutation is unavailable or forbidden.

Workflow Contract Summary

• 输入： requirements、统一计划、legacy plan、task pack 或其他可读 spec artifact，及可选 roster/output/mutation 参数。
• 输出： 默认 report-only 的结构化文档 findings、coverage、改进建议与可选 JSON envelope；只有显式 apply 授权才可修改 Markdown。
• 硬出口： 文档不可读、flag 冲突、task-pack/source-plan 漂移、format/source owner 不明确，或 mutation authority 缺失时不得写入文档。
• 权威： 原文和 source refs 提供事实，persona/LLM 判断语义充分性；producer 拥有 derived artifact 修复，review 不继承 commit/landing authority。
• 消费者： 文档 owner、spec-brainstorm、spec-plan、spec-write-tasks、spec-work 与人工 reviewer。

Interactive mode rules

• Pre-load the platform question tool before any question fires. In Claude Code, AskUserQuestion is deferred — call ToolSearch with select:AskUserQuestion once, eagerly, at the top of Interactive-mode work (before the routing question, walk-through, bulk-preview, and Phase 5 terminal question) rather than at the first question site. Other hosts don't need this preload.
• The numbered-list fallback applies only when the harness genuinely lacks a blocking question tool (ToolSearch no match, the call fails, or the mode doesn't expose it, e.g. Codex edit modes). A pending schema load is not a fallback trigger. In genuine-fallback cases present options as a numbered list and wait. Rendering a question as narrative text because the tool feels inconvenient, the model is mid-report, or the instruction was buried is a bug — a question that calls for a user decision must either fire the tool or fall back loudly, never slip past as prose.

Phase 0: Detect Mode

Check the skill arguments for flags and a document path. Tokens matching mode:*, mutation:*, output:*, roster:*, or depth:* are flags, not file paths — strip every recognized flag before resolving the remaining document path for Phase 1.

If both roster: and depth: appear, `roster:` wins. If neither appears, profile = `standard`.

mutation: and output: tokens are exact-token contracts. Fixed failure strings in this skill (flag-conflict, headless-missing-path, missing-document) are machine-facing exact contracts: emit them verbatim — never translated, localized, or rephrased. Accept only mutation:report-only, mutation:apply-fixes, and output:json. A duplicate token, multiple mutation:* tokens, multiple output:* tokens, or any unsupported mutation:* / output:* value fails closed before document read or reviewer dispatch. Return Review failed: flag-conflict-or-unsupported with the conflicting token names; do not guess precedence and do not treat those tokens as a path.

Set run-local requested_mutation to report-only or apply-fixes only when the matching exact token is present; otherwise default-report-only. Set output_mode to json only when output:json is present; otherwise text. Output mode changes rendering only — it does not grant mutation, dispatch, producer, commit, or lifecycle authority.

Set run-local delivery_mode to headless when mode:headless is present, otherwise interactive. Headless changes delivery, not mutation authority: it never upgrades default-report-only to a write policy. Only an explicit requested_mutation: apply-fixes may resolve to markdown-write; under report-only, no document write occurs in either delivery mode. output_mode is a third orthogonal choice. Headless never uses blocking prompts or interactive routing and Phase 5 returns immediately with "Review complete". Invoke a producer-owned write review via Skill("spec-doc-review", "mode:headless mutation:apply-fixes docs/plans/my-plan.md"); omit the mutation token for ordinary report-only review. Interactive references are eligible only after Phase 1 resolves mutation_policy: markdown-write.

Phase 1: Get and Analyze Document

If a document path is provided: Read it, then proceed; if the read fails, apply the missing-document gate below. If no document is specified (interactive mode): Ask which document to review, or find the most recent in docs/brainstorms/ or docs/plans/. If no document is specified (headless mode): Output this exact string, verbatim (machine-facing contract, do not localize): "Review failed: headless mode requires a document path. Re-invoke with: Skill(\"spec-doc-review\", \"mode:headless <path>\")" without dispatching agents.

Missing-document gate — verify before any dispatch. Some persona reviewers lack shell access and cannot recover a path that only exists on an un-checked-out ref. Before Phase 2, confirm every resolved path is readable on disk (location doesn't matter — an absolute path outside the checkout or another worktree is valid). If any path is unreadable, do not dispatch personas: interactive — "Document(s) not found on disk: <paths>. If they only exist on another branch, check it out (or use a worktree) and re-invoke; otherwise correct the path(s)."; headless — "Review failed: document(s) not found on disk: <paths>. Check out the branch containing them (or pass paths to files on disk) and re-invoke."

Classify Document Type

Classify by reading its content shape, not its file path. Path is a tie-breaker hint, not the primary signal.

首先检查 task-pack identity：frontmatter 含 type: task-pack 时，type: task-pack → classify as task-pack。source_plan、source_plan_hash 与 Task Pack Contract shape 用于后续 deterministic intake，不是 classification 前置条件；malformed pack 也不能降级解释成普通 plan。task-pack 分类优先于 unified requirements/plan 与通用 content-shape 分类。

First check the unified artifact contract: artifact_contract: spec-unified-plan/v1 plus artifact_readiness: requirements-only -> classify as unified-requirements (review Product Contract only; absent Planning Contract/Units/Verification/DoD is expected). Same contract plus artifact_readiness: implementation-ready -> classify as unified-plan (review Product Contract and Planning Contract with different lenses, then Implementation Units/Verification/DoD for execution completeness). Invalid progress-like readiness values (active, in_progress, completed, done) are a document-contract finding, not an execution state to honor.

STOP. 当 classification 为 `task-pack` 时，立即读取 `references/task-pack-review-lens.md`，完成 deterministic intake、current source-plan read、task-pack-specific semantic lens 与 terminal-owner mapping；这些步骤必须在 persona selection/dispatch 前完成。

Resolve Mutation Policy

After reading and classifying the document, set exactly one run-local mutation_policy, independently from delivery_mode:

• report-only — task-pack 强制使用 report-only，并记录 mutation_reason: task-pack-derived-artifact。Task pack 由 spec-write-tasks 生成且 JSON contract / human-readable mirror 必须同源；reviewer 只能返回 producer fix candidates，不得直接 patch derived artifact。显式 mutation:report-only 不覆盖这个更具体的 mandatory reason。
• markdown-write — only when requested_mutation: apply-fixes, the document is confirmed writable Markdown, and no mandatory report-only reason applies. Record mutation_reason: caller-requested-apply-fixes. Markdown safe_auto, walkthrough Apply, bulk Apply, and Open Questions append paths remain available; commit and landing remain unauthorized.
• report-only — when requested_mutation: report-only and the document is confirmed writable Markdown. Record mutation_reason: caller-requested-report-only and keep the file byte-preserving.
• report-only — when requested_mutation: default-report-only and the document is confirmed writable Markdown. Record mutation_reason: default-review-report-only; ordinary review never acquires write authority from file format or host capability.
• report-only — mandatory for HTML content or a .html artifact. Run the same reviewer roster, schema validation, confidence gate, deduplication, severity routing, Coverage, and limitations reporting, but do not invoke any document mutation path.
• report-only — also mandatory when the document is confirmed Markdown but the platform cannot write it. Record mutation_reason: write-unavailable; keep the full review and finding envelope, but do not imply that Markdown mutation was attempted.
• If extension, declared format, and content shape conflict, or the format remains ambiguous, fail closed to report-only and record mutation_reason: format-conflict-or-ambiguous in the envelope. Never guess Markdown write eligibility from the path alone.

For ordinary HTML use mutation_reason: html-artifact. A report-only request is valid in both headless and interactive delivery; interactive delivery still returns the structured report-only envelope and does not offer a mutation walkthrough.

Existing mandatory reasons retain their diagnostic meaning: task packs remain task-pack-derived-artifact, HTML remains html-artifact, write-unavailable Markdown remains write-unavailable, and format conflict/ambiguity remains format-conflict-or-ambiguous even when the caller requested apply. caller-requested-apply-fixes applies only to otherwise writable, unambiguous Markdown that is not a task pack. Without mutation:apply-fixes, ordinary writable Markdown resolves to report-only; delivery mode, JSON output, file writability, or permission settings cannot supply missing mutation authority.

Core classification rules (apply these first):

• `task-pack`: Frontmatter type: task-pack; derived metadata such as generated_by: spec-write-tasks、mode: derived、source_plan、source_plan_hash; headings Task Pack Contract、Execution Waves、Task Cards。Task-pack identity 优先，不因正文含 U-ID、files 或 verification 而归类成 plan。
• `requirements`: Frontmatter fields like actors:, flows:, acceptance_examples:; headings like Acceptance Examples, Actors, Key Flows; IDs like R1, A1, F1, AE1; prose focused on user/business problem and scope. No implementation units, per-unit file lists, or test scenarios.
• `plan`: Frontmatter fields like type: feat|fix|refactor, origin:, product_contract_source:; headings like Implementation Units, Key Technical Decisions, Risks & Dependencies; IDs like U1, U2; per-unit Goal, Files, Approach, Test scenarios, Verification; repo-relative paths.
• Tie-breaker: Content shape is authoritative over path. Mixed/sparse signals → fall back to path: docs/brainstorms/ → requirements, docs/plans/ → plan. Neither applies → default to requirements (more conservative).

STOP. If classification is genuinely ambiguous after applying the core rules above, read `references/document-classification-signals.md` for the full signal lists before proceeding to persona selection.

Pass the classification result to each persona via the {document_type} slot in the subagent template.