Product Doc Consistency

Product Document Consistency Skill

Purpose

This skill performs consistency analysis and controlled merging across a product documentation system.

本 Skill 用于对产品文档体系进行一致性分析与受控合并。

It is used when one or more product-related documents change and other documents may need to be checked, aligned, or updated.

当一个或多个产品相关文档发生修改，并可能影响其他文档时，使用本 Skill 进行检查、对齐和受控更新。

This skill must prevent meaning drift. It must not invent business rules, silently rewrite semantics, or force documents to look consistent when they actually contain unresolved business conflicts.

本 Skill 必须防止意义偏离。不得创造业务规则，不得静默改写语义，不得为了表面一致而掩盖尚未解决的业务冲突。

Core Principle

PRD is the master index of business semantics, not the sole producer of all details.

PRD 是业务语义的总索引，不是所有细节的唯一生产者。

The PRD should define and organize:

• Product goals
• Business scope
• Core concepts
• User value
• Key flows
• Cross-document semantic relationships
• Product-visible behavior
• Acceptance-level business meaning

PRD 应定义和组织：

• 产品目标
• 业务范围
• 核心概念
• 用户价值
• 关键流程
• 跨文档语义关系
• 用户可感知行为
• 验收层面的业务含义

Specialized sub-documents provide authoritative details within their own domains.

专项子文档在各自权威领域内提供细节解释权。

During consistency merging, each sub-document has final interpretive authority only within its own authority domain.

在一致性合并时，每个子文档只在自己的权威领域内拥有最终解释权。

The merge direction is decided per difference item according to topic authority, business semantic impact, and confidence level. It is not decided globally by PRD, baseline document, or document type alone.

合并方向必须按每个差异项分别判断，依据是主题权威、业务语义影响和置信度，而不是由 PRD、基准文档或文档类型全局决定。

Specialized details should update the PRD only when they affect business semantics, product-visible behavior, core process understanding, acceptance criteria, release scope, non-functional requirements promised by the product, external dependencies, or cross-document interpretation.

专项文档中的细节只有在影响业务语义、用户可感知行为、核心流程理解、验收标准、版本范围、产品承诺的非功能需求、外部依赖或跨文档解释时，才应回写 PRD。

Pure implementation details should not be forced into the PRD.

纯实现细节不应被强行写入 PRD。

Trigger

Use this skill when the user says or implies:

当用户说出或暗示以下意图时使用本 Skill：

• “合并差异”
• “执行一致性合并”
• “文档一致性合并”
• “同步这些文档的一致性”
• “根据差异报告合并文档”
• “某个产品文档改了，检查其他文档是否要同步”
• “把 PRD 和设计/规则/API/测试文档对齐”
• “检查 request、PRD、设计文档是否一致”
• “检查产品文档体系一致性”

Do not use this skill for ordinary copy editing, general summarization, or rewriting a single document unless the user explicitly asks for cross-document consistency.

除非用户明确要求跨文档一致性检查，否则不要将本 Skill 用于普通润色、总结或单文档改写。

Framework Boundary

This skill is framework-independent.

本 Skill 独立于具体文档框架。

It can work with PRD-based, Docs-as-Code, Confluence/Jira-based, OpenSpec-based, or custom documentation systems.

它可以用于 PRD 体系、Docs-as-Code、Confluence/Jira、OpenSpec 或自定义文档体系。

The assistant must not impose a documentation framework on the project.

助手不得将某种文档框架强加给项目。

When framework-specific documents are present, classify them by their actual role and authority domain rather than by framework name alone.

当存在特定框架文档时，应根据其实际角色和权威领域分类，而不是仅凭框架名称判断。

OpenSpec Boundary

This skill is independent of OpenSpec.

本 Skill 独立于 OpenSpec。

If an openspec/ directory exists, do not scan or modify it by default.

如果存在 openspec/ 目录，默认不扫描、不修改该目录。

OpenSpec documents are included only when the user explicitly provides their paths, includes them in related_documents, or registers them in document_registry.

只有当用户明确提供 OpenSpec 文件路径、将其加入 related_documents，或在 document_registry 中注册时，才纳入本次处理。

When included, OpenSpec documents must be treated as project documents with specific authority domains, not as globally authoritative sources.

纳入后，OpenSpec 文档也只作为具有特定权威领域的项目文档处理，不默认拥有全局权威。

Do not force non-OpenSpec product documents into OpenSpec structure.

不得把非 OpenSpec 产品文档强行改造成 OpenSpec 结构。

Parameters

The user may provide any combination of the following parameters.

用户可以提供以下任意组合参数。

• source_document: optional. The upstream request, original requirement, business request, or demand document. 可选。上游 request、原始需求、业务需求或需求来源文档。
• baseline_document: optional. The starting document or main comparison view for this run. It does not automatically become the authority for every topic. 可选。本次一致性检查的起点文档或主比对视图。它不会自动成为所有主题的权威来源。
• changed_document: optional. The document modified in this round. 可选。本轮发生修改的文档。
• related_documents: optional. Other product, design, rule, API, data, tracking, test, acceptance, technical, or project-specific documents to check. 可选。需要检查的其他产品、设计、规则、API、数据、埋点、测试、验收、技术或项目自定义文档。
• difference_report: optional. An AI-generated or human-generated report. Treat it as clues, not as authoritative truth. 可选。AI 或人工生成的差异报告。只能作为线索，不得视为权威事实。
• report_output: optional. Directory where generated consistency reports should be saved. It must be a directory path, not a file path. 可选。用于保存一致性报告的目录路径。必须是目录路径，不是文件路径。
• merge_mode: optional. Controls how far the consistency merge may proceed. 控制本次一致性合并允许推进到什么程度。One of:
  • scan-only: Only scan and report consistency issues. 只扫描并报告一致性问题；不生成最终改文，不修改文档。
  • propose: Analyze differences and produce merge suggestions, proposed patches, and review lists. 分析差异并输出合并建议、拟修改内容和复核清单；不修改文档。This is the default. 这是默认模式。
  • safe-merge: Allow only high-confidence, non-semantic changes such as terminology normalization, typos, formatting, numbering, and clearly outdated references. 只允许处理高置信度、非语义变更，例如术语统一、错别字、格式、编号、明显过期引用。Whether files are modified still depends on apply_strategy. 是否实际修改文件仍由 apply_strategy 决定。
  • confirmed-merge: Apply only specific items already approved by the user through confirmed_items. 只执行用户已通过 confirmed_items 确认的指定条目；不得扩大范围或顺带处理相邻问题。
• editable_documents: optional. Documents that may be modified. 可选。允许被修改的文档范围。未列入的文档不得修改。
• authority_matrix: optional. Topic-specific authority mapping. Overrides default authority rules. 可选。按主题定义的权威来源映射。它会覆盖默认权威规则。
• document_registry: optional. Project-specific document list with document types, paths, authority domains, and allowed merge directions. 可选。项目级文档注册表，用于声明文档类型、路径、权威领域和允许的合并方向。
• scope: required. The feature, module, version, or topic scope for this consistency run. It is required for report naming and must not default to general. 必填。本次一致性检查的功能、模块、版本或主题范围。用于报告命名，不得缺省为 general。
• confirmed_items: optional. Specific item IDs or decisions approved by the user for execution. 可选。用户已确认可执行的具体差异项 ID 或决策。
• preview: optional boolean. Defaults to true. When true, show proposed changes before applying them. 可选布尔值。默认 true。为 true 时，先展示拟修改内容，不直接应用修改。
• apply_strategy: optional. Controls whether and how file changes are applied. 控制是否实际修改文件，以及以什么方式修改。One of:
  • preview-only: Only output the merge plan and proposed changes. 只输出合并方案和拟修改内容，不创建、不修改文件。This is the default. 这是默认策略。
  • patch-file: Generate patch content or a separate merge proposal file if file creation is allowed. 生成 patch 内容或单独的合并建议文件，但不覆盖源文档。
  • direct-edit: Modify allowed documents directly. 直接修改允许范围内的文档。Only allowed when merge mode, editable scope, and rollback safety conditions are satisfied. 仅当合并模式、可编辑范围和回退安全条件满足时允许。
• backup_before_merge: optional boolean. Defaults to true when apply_strategy is direct-edit. 可选布尔值。当 apply_strategy 为 direct-edit 时默认 true。用于在直接修改前创建备份。
• rollback_plan: optional boolean. Defaults to true. Output rollback information for applied or proposed changes. 可选布尔值。默认 true。用于输出已应用或拟应用修改的回退信息。
• dry_run: optional boolean. Alias of preview: true and apply_strategy: preview-only. 可选布尔值。等价于 preview: true 和 apply_strategy: preview-only，即只演练不修改。

If required information is missing, ask for the minimum missing information before proceeding.

如果必要信息缺失，只询问推进所需的最少信息。

Safety Defaults

This skill is conservative by default.

本 Skill 默认采取保守策略。

Unless the user explicitly requests file modification:

除非用户明确要求修改文件：

• merge_mode defaults to propose
• preview defaults to true
• apply_strategy defaults to preview-only
• rollback_plan defaults to true
• No source document is modified
• If report_output is missing, reports are output in the conversation only

默认行为是：

• merge_mode 默认为 propose
• preview 默认为 true
• apply_strategy 默认为 preview-only
• rollback_plan 默认为 true
• 不修改任何源文档
• 如果未提供 report_output，报告只在对话中输出

Direct editing requires explicit permission or an unambiguous user request.

直接编辑必须有明确授权或明确的用户请求。

If editable_documents is missing, do not modify files unless the user clearly requested direct modification.

如果未提供 editable_documents，除非用户明确要求直接修改，否则不得修改文件。

If apply_strategy is direct-edit, preserve rollback ability before applying changes.

如果 apply_strategy 为 direct-edit，必须先确保可回退，再应用修改。

Default Behavior

If merge_mode is missing, use propose.

如果未提供 merge_mode，使用 propose。

If baseline_document is missing, infer a candidate baseline for organizing the comparison, but do not use the inferred baseline as authority for medium-risk or high-risk changes. Such changes require human confirmation.

如果未提供 baseline_document，可以推测一个候选基准用于组织比对，但不得将推测出的基准作为中高风险变更的裁决依据。此类变更必须人工确认。

If difference_report is provided, verify important claims against the source documents before acting on them.

如果提供了 difference_report，必须先回到源文档验证重要结论，再执行处理。

If scope is missing, ask the user to provide it before generating or saving any report. Do not use general or any other fallback scope.

如果缺少 scope，必须先询问用户补充，再生成或保存任何报告。不得使用 general 或其他兜底范围。

If report_output is missing, output generated reports in the conversation only. If report_output is provided, treat it as an output directory and generate the report filename automatically. Do not accept a manually named report file path.

如果未提供 report_output，生成的报告只在对话中输出。如果提供了 report_output，将其视为输出目录，并自动生成报告文件名。不得接受人工命名的报告文件路径。

If report_output ends with .md, warn that V10 expects a directory path and ask whether to use the parent directory.

如果 report_output 以 .md 结尾，提示 V10 期望目录路径，并询问是否使用其父目录。

Creating a report file through report_output is separate from modifying source documents. It must not be treated as permission to edit PRD or related documents.

通过 report_output 创建报告文件不同于修改源文档。不得将其理解为允许编辑 PRD 或相关文档。

If an openspec/ directory exists but is not explicitly included, exclude it from scanning and modification.

如果存在 openspec/ 目录但未被明确纳入，则排除扫描和修改。

If dry_run is true, force preview: true and apply_strategy: preview-only.

如果 dry_run 为 true，强制使用 preview: true 和 apply_strategy: preview-only。

Merge Modes

merge_mode controls the decision boundary of the consistency merge: whether the assistant only scans, proposes changes, safely merges low-risk items, or executes user-confirmed items.

merge_mode 控制一致性合并的决策边界：助手是只扫描、只提出建议、自动合并低风险项，还是执行用户已确认的条目。

It does not alone decide whether files are modified. File modification is controlled by apply_strategy.

它本身不决定是否实际修改文件。是否修改文件由 apply_strategy 控制。

scan-only

Only inspect documents and identify consistency issues.

只检查文档并识别一致性问题。

Output:

输出：

• Difference list
• Impacted documents
• Authority source
• Suggested merge direction
• Risk level
• Suggested next action

包括：

• 差异清单
• 受影响文档
• 权威来源
• 建议合并方向
• 风险等级
• 建议下一步

Do not propose final text and do not modify documents.

不生成最终改文，不修改文档。

propose

Analyze differences and produce a merge proposal.

分析差异并生成合并建议。

Output:

输出：

• Auto-merge candidate list
• Human-review list
• Business-decision list
• Proposed patches or rewritten sections
• Rationale for each proposed change

包括：

• 可自动合并候选项
• 需人工复核清单
• 需业务决策清单
• 拟修改 patch 或章节改写建议
• 每项建议的依据

Do not modify documents.

不修改文档。

safe-merge

Apply only high-confidence, non-semantic changes.

只处理高置信度、非语义性变更。

Allowed changes:

允许处理：

• Terminology normalization when meaning is clearly identical
• Typo fixes
• Formatting and heading consistency
• Numbering and table layout consistency
• Repeated wording normalization
• References or links that are obviously outdated and directly traceable

包括：

• 含义明确相同的术语统一
• 错别字修正
• 格式和标题层级统一
• 编号和表格样式统一
• 重复表述规范化
• 明显过期且可追溯的引用或链接修正

Do not apply medium-confidence or low-confidence changes.

不得处理中置信度或低置信度变更。

confirmed-merge

Apply only specific changes that the user has already approved.

只执行用户已经确认的具体变更项。

Rules:

规则：

• Only execute confirmed items.
• Do not expand the scope.
• Do not reinterpret approval as permission to resolve adjacent conflicts.
• If a new conflict is discovered while editing, stop that item and move it to human review.

要求：

• 只执行已确认条目。
• 不得扩大范围。
• 不得把确认理解为可顺带处理相邻冲突。
• 编辑过程中发现新冲突时，停止该项并转入人工复核。

Apply Strategies

apply_strategy controls whether and how file changes are applied.

apply_strategy 控制是否实际修改文件，以及如何修改文件。

It is separate from merge_mode.

它与 merge_mode 是两个不同维度。

preview-only

Only output the merge plan and proposed changes.

只输出合并方案和拟修改内容。

Do not create or modify files.

不创建、不修改文件。

This is the default strategy.

这是默认策略。

patch-file

Generate patch content or a separate merge proposal file if the user allows file creation.

如果用户允许创建文件，则生成 patch 内容或单独的合并建议文件。

If report_output is provided, save the generated difference report, merge plan, or final consistency report under that directory using the standard report filename when file creation is allowed.

如果提供了 report_output，且允许创建文件，则按统一报告文件名将生成的差异报告、合并方案或最终一致性报告保存到该目录下。

The report file name must be generated automatically using the standard report naming format.

报告文件名必须按统一报告命名格式自动生成。

Do not directly overwrite source documents.

不直接覆盖源文档。

Use this when the user wants a reviewable artifact before applying changes.

当用户希望先获得可审查的合并产物时使用。

direct-edit

Modify allowed documents directly.

直接修改允许范围内的文档。

Only allowed when:

仅在以下条件满足时允许：

• merge_mode is safe-merge or confirmed-merge
• editable_documents is provided or the user explicitly allows editing
• Medium-confidence and low-confidence items are excluded or confirmed
• Rollback ability is preserved

条件包括：

• merge_mode 为 safe-merge 或 confirmed-merge
• 已提供 editable_documents，或用户明确允许编辑
• 中置信度和低置信度项已排除或已确认
• 已保留回退能力

Rollback Safety

When direct editing is allowed, the assistant must preserve rollback ability.

当允许直接编辑时，助手必须保留回退能力。

If the workspace is a git repository:

如果工作区是 git 仓库：

• Check working tree state before editing.
• Do not revert unrelated user changes.
• After editing, report modified files.
• Use the generated diff as the rollback reference.
• Do not run destructive git commands unless explicitly requested.

要求：

• 编辑前检查工作区状态。
• 不得回退用户无关改动。
• 编辑后报告修改文件。
• 使用生成的 diff 作为回退依据。
• 未经明确要求，不得运行破坏性 git 命令。

If the workspace is not a git repository:

如果工作区不是 git 仓库：

• Prefer patch-file instead of direct-edit.
• If direct editing is explicitly required, create backup copies before direct edits when allowed.
• If backup copies cannot be created, output proposed patches and ask for confirmation before editing.

要求：

• 优先使用 patch-file，而不是 direct-edit。
• 如果用户明确要求直接编辑，且允许创建备份，则编辑前创建备份副本。
• 如果无法创建备份，先输出拟修改 patch 并请求确认，再编辑。

For every applied change, record:

每个已应用变更都必须记录：

• File path
• Difference item ID
• Original text reference
• New text reference
• Reason for change
• Confidence level
• Rollback method

包括：

• 文件路径
• 差异项 ID
• 原文位置或原文引用
• 新文位置或新文引用
• 修改原因
• 置信度
• 回退方式

Open Document System

Document types are open-ended.

文档类型是开放的。

The skill must not assume that product documentation is limited to PRD, flow design, rule design, API documents, data dictionaries, or test cases.

本 Skill 不得假设产品文档只包含 PRD、流转设计、规则设计、API 文档、数据字典或测试用例。

If the project contains other document types, infer their authority domains from:

如果项目中存在其他文档类型，应从以下信息推断其权威领域：

• Document title
• File name
• Directory location
• Section headings
• Repeated concepts
• Tables and field definitions
• Diagrams or flow descriptions
• Explicit statements such as “本文档定义... ”
• Relationship to other documents
• User-provided context
• document_registry
• authority_matrix

For each unknown or project-specific document, assign:

对于未知或项目特定文档，应标注：

• document_type
• likely_authority_domain
• authority_confidence
• suggested_merge_direction
• needs_human_confirmation

If the authority domain cannot be inferred with confidence, mark the document as unknown authority and ask for confirmation.

如果无法可靠推断权威领域，将其标记为 unknown authority 并请求用户确认。

Extensible Authority Matrix

Authority is topic-specific and extensible. The following document types are common examples, not a closed set.

权威来源按主题划分，并且可扩展。以下文档类型只是常见示例，不是封闭集合。

The matrix may be extended or overridden by authority_matrix or document_registry.

该矩阵可通过 authority_matrix 或 document_registry 扩展或覆盖。

More detailed does not automatically mean more authoritative.

更详细不代表天然更权威。

A specialized document is authoritative only within its own authority domain.

专项文档只在自己的权威领域内具有权威性。

Directionality Rule

This skill does not assume one-way merging from PRD to all other documents.

本 Skill 不假设从 PRD 到其他文档的单向合并。

Consistency updates may flow in any direction depending on topic authority.

一致性更新可以根据主题权威向任意方向流动。

Examples:

示例：

• PRD -> related documents, when PRD is authoritative for product scope, goals, user scenarios, business value, priority, or product-visible behavior.
• Request document -> PRD, when the PRD omitted or changed an upstream requirement without clear productization rationale.
• PRD -> request alignment report, when PRD intentionally refines, splits, scopes, or productizes the original request.
• Flow design -> PRD or tests, when flow nodes, state transitions, or process sequence are authoritative and affect product-visible behavior.
• Rule design -> PRD or tests, when eligibility, calculation, priority, or exception logic is authoritative and affects business semantics.
• Architecture design -> PRD, when architecture constraints affect non-functional requirements, release feasibility, security, performance, deployment boundaries, or user-visible capabilities.
• Detailed design -> PRD, when technical dependencies affect product behavior, acceptance, integration constraints, or external commitments.
• API spec or data dictionary -> PRD, page design, tests, or API consumers, when field definitions or contracts affect product-visible behavior.
• Permission matrix -> PRD, rule design, or tests, when role access affects behavior or acceptance.
• Tracking spec -> PRD or acceptance criteria, when analytics requirements are part of product acceptance.
• Test cases -> PRD or specialized docs, when tests reveal missing acceptance criteria, unverifiable requirements, boundary omissions, or exception scenarios.

The merge direction must be decided per difference item, not globally per run.

合并方向必须按差异项逐项判断，不能按整轮任务全局决定。

PRD Update Boundary

Specialized documents may update PRD only when their details affect at least one of the following:

专项文档只有在其细节影响以下至少一类内容时，才可建议回写 PRD：

• Business semantics
• Product-visible behavior
• User role or permission behavior
• Core flow understanding
• Acceptance criteria
• Release scope
• External dependency or integration constraint
• Non-functional requirement promised by the product
• Cross-document interpretation

包括：

• 业务语义
• 用户可感知行为
• 用户角色或权限行为
• 核心流程理解
• 验收标准
• 版本范围
• 外部依赖或集成约束
• 产品承诺的非功能需求
• 跨文档解释

Do not force the following into PRD:

以下内容不得强行写入 PRD：

• Pure implementation details
• Internal-only technical choices
• Temporary debugging behavior
• Low-level data storage details
• Non-user-visible refactoring details
• Test implementation mechanics
• Framework-specific structure from OpenSpec or other documentation systems

包括：

• 纯实现细节
• 仅内部可见的技术选型
• 临时调试行为
• 低层数据存储细节
• 用户不可感知的重构细节
• 测试实现机制
• OpenSpec 或其他文档框架的特定结构

Source-To-PRD Alignment

If source_document exists and baseline_document is PRD, first compare the source document with the PRD before comparing PRD with related documents.

如果存在 source_document 且 baseline_document 是 PRD，应先比较需求来源文档与 PRD，再比较 PRD 与其他相关文档。

This step checks whether the PRD correctly productizes the upstream request.

此步骤用于检查 PRD 是否正确完成了对上游需求的产品化转化。

Classify each source-to-PRD difference as:

每个 source-to-PRD 差异应分类为：

• Requirement preserved
• Requirement refined
• Requirement split by version or scope
• Requirement omitted
• Requirement changed
• New PRD requirement not found in source
• Ambiguous transformation
• Business conflict

对应：

• 需求已保留
• 需求已细化
• 按版本或范围拆分
• 需求被遗漏
• 需求被改变
• PRD 新增了来源文档中不存在的需求
• 转化关系不明确
• 业务冲突

Do not assume the source document directly overrides the PRD.

不得假设需求来源文档直接覆盖 PRD。

If the PRD intentionally refines, narrows, stages, or restructures the request, mark it as requirement transformation rather than inconsistency.

如果 PRD 对需求进行了有意细化、收窄、分期或重构，应标记为需求转化，而不是直接标记为不一致。

If the PRD omits or changes a source requirement without clear rationale, mark it for human review or business decision.

如果 PRD 在无明确理由的情况下遗漏或改变来源需求，应标记为人工复核或业务决策。

After source-to-PRD alignment, continue with topic-authority-based consistency analysis across related documents.

完成 source-to-PRD 对齐后，再继续进行基于主题权威的相关文档一致性分析。

Difference Classification

Classify each difference into one of the following types:

每个差异应分类为以下类型之一：

• Terminology inconsistency
• Format or structure inconsistency
• Typo or obvious wording issue
• Description granularity difference
• Source-to-PRD transformation difference
• Requirement omission
• Requirement scope or version split
• Flow node mismatch
• State definition mismatch
• Business rule conflict
• Calculation logic conflict
• Permission or role conflict
• Field or data definition conflict
• API contract conflict
• Architecture constraint conflict
• Detailed design dependency conflict
• Non-functional requirement conflict
• Tracking/event conflict
• Acceptance/test mismatch
• Version or scope mismatch
• Missing reference or outdated reference
• Implementation detail leakage
• Framework boundary issue
• Unknown document authority
• Ambiguous conflict

Confidence Rules

High Confidence: Auto-Merge Eligible

Only high-confidence items may be automatically merged in safe-merge.

只有高置信度项目才允许在 safe-merge 中自动合并。

Examples:

示例：

• Same concept uses different names, and equivalence is explicit or obvious.
• Formatting, numbering, title hierarchy, table style, or reference style differs.
• Clear typo or duplicated text.
• A document reference points to an older name after a confirmed rename.
• Wording differs but does not change behavior, condition, role, state, amount, time, priority, scope, interface contract, data definition, or acceptance criteria.

包括：

• 同一概念使用不同名称，且等价关系明确。
• 格式、编号、标题层级、表格样式或引用样式不一致。
• 明显错别字或重复文本。
• 已确认重命名后，文档引用仍指向旧名称。
• 文案差异不改变行为、条件、角色、状态、金额、时间、优先级、范围、接口契约、数据定义或验收标准。

Medium Confidence: Suggest + Human Confirmation

Do not automatically merge.

不得自动合并。

Examples:

示例：

• PRD summary and detailed design describe the same process at different granularity.
• A flow node is split or merged in one document but not reflected elsewhere.
• A rule is stated generally in PRD but precisely in rule design.
• A source requirement appears to be refined or scoped in PRD.
• A field appears in page design but not in API or data specs.
• Acceptance criteria do not fully cover updated behavior.
• A specialized document suggests a PRD update but the product-visible impact is unclear.
• Architecture or detailed design adds a constraint that may affect non-functional requirements.

Low Confidence: Human Decision Required

Never automatically merge.

绝不自动合并。

Examples:

示例：

• Business rule contradiction.
• Calculation formula or threshold conflict.
• State transition conflict.
• Permission or role conflict.
• API contract conflict that changes behavior.
• Data field meaning conflict.
• Architecture constraint that changes release scope, performance commitment, security level, deployment boundary, or product feasibility.
• Tracking logic conflict that changes reporting meaning.
• Version scope or release boundary conflict.
• Source requirement omitted or changed without clear rationale.
• Unknown authority conflict.
• Any case where resolving the conflict requires deciding what the product should do.

Meaning Drift Prevention

The assistant must follow these rules:

助手必须遵守以下规则：

• Do not invent new business rules.
• Do not merge two similar-looking terms if their meanings may differ.
• Do not delete conflicting content to make documents look consistent.
• Do not silently change amounts, ratios, thresholds, time limits, priorities, state transitions, roles, permissions, formulas, interface contracts, data constraints, or exception logic.
• Do not let a general PRD statement overwrite a specialized design, rule, API, data, permission, tracking, architecture, detailed design, or test document without topic-authority support.
• Do not let a specialized implementation detail rewrite product goals, business scope, user value, or confirmed version boundary.
• Do not assume more detailed means more authoritative.
• Do not rewrite large sections when a minimal local edit is enough.
• Do not treat an AI-generated difference report as authoritative.
• Do not include or modify openspec/ unless explicitly requested.
• Every proposed change must have a traceable source: original text, changed text, difference report item, user instruction, or approved authority matrix.
• If authority cannot be determined, stop automatic merging and ask for human decision.

对应中文规则：

• 不得创造新的业务规则。
• 若两个相似术语含义可能不同，不得合并。
• 不得删除冲突内容来制造表面一致。
• 不得静默修改金额、比例、阈值、时限、优先级、状态流转、角色、权限、公式、接口契约、数据约束或异常逻辑。
• 没有主题权威支持时，不得用 PRD 的概括性描述覆盖专项设计、规则、API、数据、权限、埋点、架构、详细设计或测试文档。
• 不得让专项文档中的实现细节改写产品目标、业务范围、用户价值或已确认的版本边界。
• 不得假设“更详细”就“更权威”。
• 能局部最小修改时，不得大段重写。
• 不得把 AI 生成的差异报告视为权威事实。
• 未经明确请求，不得纳入或修改 openspec/。
• 每个拟修改项必须可追溯到原文、变更文本、差异报告条目、用户指令或已批准的权威矩阵。
• 如果无法确定权威来源，停止自动合并并请求人工决策。

Workflow

Step 1: Resolve Parameters

Determine:

识别以下参数：

• source_document
• baseline_document
• changed_document
• related_documents
• difference_report
• report_output
• merge_mode
• editable_documents
• authority_matrix
• document_registry
• scope
• confirmed_items
• preview
• apply_strategy
• backup_before_merge
• rollback_plan
• dry_run

If merge_mode is missing, use propose.

如果缺少 merge_mode，使用 propose。

If dry_run is true, force preview: true and apply_strategy: preview-only.

如果 dry_run 为 true，强制使用 preview: true 和 apply_strategy: preview-only。

If document scope is unclear, ask one concise clarification question.

如果文档范围不明确，只问一个简洁澄清问题。

If openspec/ exists but is not explicitly included, exclude it.

如果存在 openspec/ 但未明确纳入，则排除。

Step 2: Build Document Map

For each document, identify:

对每个文档识别：

• Document path or title
• Document type
• Main topics covered
• Likely authority areas
• Authority confidence
• Version or date if available
• Sections relevant to the reported differences
• Whether the document is editable in this run
• Whether the document is part of OpenSpec or another framework-specific system

Step 3: Source-To-Baseline Alignment

If source_document exists and the baseline is PRD, compare the source document with the PRD first.

如果存在 source_document 且基准为 PRD，先比较来源文档与 PRD。

For each difference:

对每个差异：

• Identify whether the PRD preserved, refined, split, omitted, changed, or added requirements.
• Determine whether the difference is intentional productization or unresolved inconsistency.
• Do not automatically rewrite PRD from the source document unless the change is explicitly confirmed or high-confidence non-semantic.
• Mark unresolved requirement transformation issues for human review.

Step 4: Verify Differences

For each difference report item or discovered inconsistency:

对每个差异报告条目或发现的不一致：

• Locate the source text in relevant documents.
• Confirm whether the difference actually exists.
• Identify the affected concept, rule, flow, state, field, API, permission, tracking event, architecture constraint, technical dependency, or acceptance point.
• Classify the difference type.
• Assign topic authority if possible.
• Assign authority confidence.
• Assign confidence level.
• Determine suggested merge direction.
• Determine target document or documents.
• Determine whether the change affects business semantics.
• Determine whether the change is allowed by framework boundaries.

If a reported difference cannot be verified, mark it as unverified.

如果无法验证报告中的差异，将其标记为 unverified。

Step 5: Decide Handling

For each difference, assign one handling action:

对每个差异分配一个处理动作：

• auto-merge: high confidence and non-semantic.
• suggest-review: medium confidence or requires domain confirmation.
• must-decide: low confidence or business decision required.
• ignore: false positive, obsolete, framework-excluded, or out of scope.
• needs-info: not enough information.

Step 6: Produce Merge Plan

Before modifying documents, produce a structured merge plan unless the user explicitly requested safe-merge, apply_strategy: direct-edit, and all changes are high-confidence.

除非用户明确要求 safe-merge、apply_strategy: direct-edit，且所有变更均为高置信度，否则在修改文档前必须生成结构化合并方案。

The plan must include:

方案必须包括：

• Item ID
• Difference type
• Difference summary
• Documents involved
• Source location
• Authority source
• Authority confidence
• Suggested merge direction
• Target document or documents
• Risk level
• Business semantic impact
• Proposed handling
• Proposed text change if applicable
• Rationale
• Rollback note if applicable

Step 7: Apply Or Preview Controlled Changes

Respect apply_strategy.

遵守 apply_strategy。

If apply_strategy is preview-only:

如果 apply_strategy 为 preview-only：

• Do not modify files.
• Output proposed patches or section replacements.
• If report_output is provided, mention that no report file was created because preview-only does not create files unless the user explicitly allowed report file creation.

对应：

• 不修改文件。
• 输出拟修改 patch 或章节替换建议。
• 如果提供了 report_output，需要说明未创建报告文件，因为 preview-only 不创建文件，除非用户明确允许创建报告文件。

If apply_strategy is patch-file:

如果 apply_strategy 为 patch-file：

• Generate patch content or a separate merge proposal file only if file creation is allowed.
• Save the generated report to report_output when it is provided and file creation is allowed.
• Do not overwrite source documents.

If apply_strategy is direct-edit:

如果 apply_strategy 为 direct-edit：

• Only edit documents listed in editable_documents, unless the user explicitly allowed broader edits.
• Only apply items allowed by merge_mode.
• Save the generated report to report_output when it is provided and file creation is allowed.
• Preserve rollback information.
• Create backups first when backup_before_merge is true and backups are allowed.
• Prefer minimal edits.
• Do not modify openspec/ unless explicitly included and editable.
• Stop and move item to human review if unexpected conflict appears.

Step 8: Output Final Report

Always output a report with:

始终输出最终报告，包括：

• Merge mode used
• Apply strategy used
• Preview status
• Report output path if provided
• Documents reviewed
• Documents modified or proposed for modification
• Automatically merged items
• Items requiring human review
• Items requiring business decision
• Items ignored or unverified
• Framework-excluded items
• Rollback information
• Remaining risks
• Recommended next step

Output Format

Use the following structure.

使用以下输出结构。

Report Language

Generated reports must use Chinese as the primary language for explanatory content.

生成的报告中，说明性内容必须以中文为主。

Rules:

规则：

• Table column names may remain English.
• Status codes may remain English, such as pending-review, confirmed, must-decide, and applied.
• Technical parameter names may remain English, such as merge_mode, apply_strategy, confirmed_items, and report_output.
• Difference summaries must be written in Chinese.
• Risk descriptions must be written in Chinese.
• Suggested decisions must be written in Chinese.
• Decision notes must be written in Chinese.
• Rationale, basis, residual risks, rollback notes, and next steps must be written in Chinese.
• If an English term is necessary, keep it, but explain the meaning in Chinese when it affects user understanding.

对应规则：

• 表格列名可以保持英文。
• 状态码可以保持英文，例如 pending-review、confirmed、must-decide、applied。
• 技术参数名可以保持英文，例如 merge_mode、apply_strategy、confirmed_items、report_output。
• 差异描述必须使用中文。
• 风险说明必须使用中文。
• 处理建议必须使用中文。
• 确认说明必须使用中文。
• 修改依据、剩余风险、回退说明、下一步建议必须使用中文。
• 如必须保留英文术语，应在影响理解时补充中文解释。

Even when table headers and status codes remain English, generated report descriptions, table cell explanations, proposed changes, decision notes, and risk explanations must be Chinese-first.

即使表格列名和状态码保留英文，报告中的描述、表格内容、拟修改内容、确认说明和风险解释也必须以中文为主。

Markdown Table Style

All generated Markdown tables must use markdownlint compact-compatible pipe spacing.

所有生成的 Markdown 表格必须使用 markdownlint compact 兼容的管道符空格格式。

Required style:

必须使用：

| Column A | Column B |
| --- | --- |
| Value A | Value B |

Do not generate:

不得生成：

|Column A|Column B|
| ---without-spaces--- | ---without-spaces--- |
|Value A|Value B|

Rules:

规则：

• Each table pipe must have spaces around cell content.
• Separator rows must use spaced separators such as | --- | --- |; do not omit spaces around separator cells.
• Alignment markers are allowed only with spaces, such as | ---: |, | :--- |, or | :---: |.

Report Item Status

Every difference item in report_output must include a status field.

report_output 中的每个差异项都必须包含状态字段。

Allowed statuses:

允许的状态：

Required Fields For Each Difference Item

Every difference item in report_output must include enough fields to support review and later confirmed-merge.

report_output 中的每个差异项都必须包含足够字段，以支持人工复核和后续 confirmed-merge。

Required fields:

必填字段：

Final Change Plan and Decision Note must be present in every item, including pending-review items generated by propose + patch-file + report_output.

Final Change Plan 和 Decision Note 必须出现在每个差异项中，包括由 propose + patch-file + report_output 生成的 pending-review 条目。

For Status: pending-review, use explicit placeholders:

Status: pending-review 时使用明确占位值：

• Final Change Plan: 待用户确认；当前仅为 AI 建议，见 Proposed Change。
• Decision Note: 待用户确认。

For Status: applied, Final Change Plan must describe the actual applied change, and Decision Note must state that the item was manually or automatically applied and no longer needs confirmed-merge.

Status: applied 时，Final Change Plan 必须描述实际已落地的修改方案，Decision Note 必须说明该项已由人工或自动流程执行，不再进入 confirmed-merge。

For any item with Status: confirmed, Target Document, Final Change Plan, and Decision Note must be present and specific.

任何 Status: confirmed 的条目都必须包含明确的 Target Document、Final Change Plan 和 Decision Note。

If a confirmed item is missing any required execution field, the assistant must not execute it. Mark the item as needs-info for this run and explain what field is missing.

如果已确认条目缺少任何执行必填字段，助手不得执行该条目。本轮应将其标记为 needs-info，并说明缺少哪个字段。

Confirmation Ownership

The assistant must not set any item status to confirmed by default.

助手不得默认将任何差异项状态设置为 confirmed。

Only the user can explicitly confirm an item.

只有用户可以明确确认差异项。

The assistant may suggest that an item is confirmable, but the status must remain pending-review until the user explicitly confirms it.

助手可以建议某项“可确认”，但在用户明确确认前，状态必须保持为 pending-review。

A report generated by propose must not mark items as confirmed unless the user already provided explicit confirmation for those exact item IDs.

由 propose 生成的报告不得将条目标记为 confirmed，除非用户已经明确确认这些具体 ID。

Scope Normalization

scope is required and must be normalized before report filename generation.

scope 必填，并且在生成报告文件名前必须规范化。

Rules:

规则：

• Use - as the only separator.
• Replace spaces, commas, Chinese commas, slashes, pipes, colons, semicolons, and consecutive punctuation with -.
• Remove leading and trailing -.
• Collapse consecutive - into one.
• Keep meaningful Chinese, English, numbers, and safe hyphen characters.
• Do

…(truncated)