Merge branch 'main' into feat/editorial-review-translation

Replace verbose step-by-step enumeration with concise instructions
that trust the model to infer obvious sub-tasks. Same coverage,
roughly half the token count.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/zh-cn/explanation/established-projects-faq.md

@@ -1,60 +1,62 @@
 ---
 title: "既有项目常见问题"
-description: 关于在既有项目上使用 BMad 方法的常见问题
+description: 关于在既有项目上使用 BMad Method 的常见问题
 sidebar:
   order: 8
 ---
-关于使用 BMad 方法（BMM）在既有项目上工作的常见问题的快速解答。
+关于在 established projects（既有项目）中使用 BMad Method 的高频问题，快速说明如下。
 
 ## 问题
 
-- [我必须先运行 document-project 吗？](#我必须先运行-document-project-吗)
-- [如果我忘记运行 document-project 怎么办？](#如果我忘记运行-document-project-怎么办)
-- [我可以在既有项目上使用快速流程吗？](#我可以在既有项目上使用快速流程吗)
-- [如果我的现有代码不遵循最佳实践怎么办？](#如果我的现有代码不遵循最佳实践怎么办)
+- [我必须先运行文档梳理工作流吗？](#我必须先运行文档梳理工作流吗)
+- [如果我忘了运行文档梳理怎么办？](#如果我忘了运行文档梳理怎么办)
+- [既有项目可以直接用 Quick Flow 吗？](#既有项目可以直接用-quick-flow-吗)
+- [如果现有代码不符合最佳实践怎么办？](#如果现有代码不符合最佳实践怎么办)
+- [什么时候该从 Quick Flow 切到完整方法？](#什么时候该从-quick-flow-切到完整方法)
 
-### 我必须先运行 document-project 吗？
+### 我必须先运行文档梳理工作流吗？
 
-强烈推荐，特别是如果：
+不绝对必须，但通常强烈建议先运行 `bmad-document-project`，尤其当：
+- 项目文档缺失或明显过时
+- 新成员或智能体难以快速理解现有系统
+- 你希望后续 `workflow` 基于真实现状而不是猜测执行
 
-- 没有现有文档
-- 文档已过时
-- AI 智能体需要关于现有代码的上下文
+如果你已有完整且最新的文档（包含 `docs/index.md`），并且能通过其他方式提供足够上下文，也可以跳过。
 
-如果你拥有全面且最新的文档，包括 `docs/index.md`，或者将使用其他工具或技术来帮助智能体发现现有系统，则可以跳过此步骤。
+### 如果我忘了运行文档梳理怎么办？
 
-### 如果我忘记运行 document-project 怎么办？
+可以随时补跑，不影响你继续推进当前任务。很多团队会在迭代中期或里程碑后再运行一次，用来把“代码现状”回写到文档里。
 
-不用担心——你可以随时执行。你甚至可以在项目期间或项目之后执行，以帮助保持文档最新。
+### 既有项目可以直接用 Quick Flow 吗？
 
-### 我可以在既有项目上使用快速流程吗？
+可以。Quick Flow（例如 `bmad-quick-dev`）在既有项目里通常很高效，尤其适合：
+- 小功能增量
+- 缺陷修复
+- 风险可控的局部改动
 
-可以！快速流程在既有项目上效果很好。它将：
+它会尝试识别现有技术栈、代码模式和约定，并据此生成更贴近现状的实现方案。
 
-- 自动检测你的现有技术栈
-- 分析现有代码模式
-- 检测约定并请求确认
-- 生成尊重现有代码的上下文丰富的技术规范
+### 如果现有代码不符合最佳实践怎么办？
 
-非常适合现有代码库中的错误修复和小功能。
+工作流会优先问你：“是否沿用当前约定？”你可以主动选择：
+- **沿用**：优先保持一致性，降低短期改动风险
+- **升级**：建立新标准，并在 tech-spec 或架构中写明迁移理由与范围
 
-### 如果我的现有代码不遵循最佳实践怎么办？
+BMad Method 不会强制“立即现代化”，而是把决策权交给你。
 
-快速流程会检测你的约定并询问："我应该遵循这些现有约定吗？"你决定：
+### 什么时候该从 Quick Flow 切到完整方法？
 
-- **是** → 与当前代码库保持一致
-- **否** → 建立新标准（在技术规范中记录原因）
+当任务出现以下信号时，建议从 Quick Flow 升级到完整 BMad Method：
+- 改动跨多个 `epic` 或多个子系统
+- 需要明确 `architecture` 决策，否则容易冲突
+- 涉及较大协作面、较高回归风险或复杂验收要求
 
-BMM 尊重你的选择——它不会强制现代化，但会提供现代化选项。
+如果你不确定，先让 `bmad-help` 判断当前阶段更稳妥的 workflow。
 
-**有未在此处回答的问题吗？** 请[提出问题](https://github.com/bmad-code-org/BMAD-METHOD/issues)或在 [Discord](https://discord.gg/gk8jAdXWmj) 中提问，以便我们添加它！
+**还有问题？** 欢迎在 [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) 或 [Discord](https://discord.gg/gk8jAdXWmj) 提问。
 
----
-## 术语说明
+## 继续阅读
 
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **Quick Flow**：快速流程。BMad 方法中的一种工作流程，用于快速处理既有项目。
-- **spec**：规范。描述技术实现细节和标准的文档。
-- **stack**：技术栈。项目所使用的技术组合，包括框架、库、工具等。
-- **conventions**：约定。代码库中遵循的编码风格、命名规则等规范。
-- **modernization**：现代化。将旧代码或系统更新为更现代的技术和最佳实践的过程。
+- [既有项目（How-to）](../how-to/established-projects.md)
+- [项目上下文（Explanation）](./project-context.md)
+- [管理项目上下文（How-to）](../how-to/project-context.md)

docs/zh-cn/explanation/preventing-agent-conflicts.md

@@ -5,133 +5,112 @@ sidebar:
   order: 4
 ---
 
-当多个 AI 智能体实现系统的不同部分时，它们可能会做出相互冲突的技术决策。架构文档通过建立共享标准来防止这种情况。
+当多个 AI 智能体并行实现系统时，冲突并不罕见。`architecture` 的作用，就是在 `solutioning` 阶段先统一关键决策，避免到 `epic/story` 实施时才暴露分歧。
 
-## 常见冲突类型
+## 冲突最常出现在哪些地方
 
 ### API 风格冲突
 
-没有架构时：
-- 智能体 A 使用 REST，路径为 `/users/{id}`
+没有架构约束时：
+- 智能体 A 使用 REST，路径是 `/users/{id}`
 - 智能体 B 使用 GraphQL mutations
-- 结果：API 模式不一致，消费者困惑
+- 结果：接口模式不一致，调用方和集成层都变复杂
 
-有架构时：
-- ADR 指定："所有客户端-服务器通信使用 GraphQL"
-- 所有智能体遵循相同的模式
+有架构约束时：
+- ADR 明确规定：“客户端与服务端统一使用 GraphQL”
+- 所有智能体遵循同一套 API 规则
 
-### 数据库设计冲突
+### 数据库与命名冲突
 
-没有架构时：
-- 智能体 A 使用 snake_case 列名
-- 智能体 B 使用 camelCase 列名
-- 结果：模式不一致，查询混乱
+没有架构约束时：
+- 智能体 A 使用 `snake_case` 列名
+- 智能体 B 使用 `camelCase` 列名
+- 结果：schema 不一致，查询与迁移成本上升
 
-有架构时：
-- 标准文档指定命名约定
-- 所有智能体遵循相同的模式
+有架构约束时：
+- 标准文档统一命名约定和迁移策略
+- 所有智能体按同一模式实现
 
 ### 状态管理冲突
 
-没有架构时：
-- 智能体 A 使用 Redux 管理全局状态
+没有架构约束时：
+- 智能体 A 使用 Redux
 - 智能体 B 使用 React Context
-- 结果：多种状态管理方法，复杂度增加
+- 结果：状态层碎片化，维护复杂度增加
 
-有架构时：
-- ADR 指定状态管理方法
-- 所有智能体一致实现
+有架构约束时：
+- ADR 明确状态管理方案
+- 不同 `story` 的实现保持一致
 
-## 架构如何防止冲突
+## architecture 如何前置消解冲突
 
-### 1. 通过 ADR 明确决策
+### 1. 用 ADR 固化关键决策
 
-每个重要的技术选择都记录以下内容：
-- 上下文（为什么这个决策很重要）
-- 考虑的选项（有哪些替代方案）
-- 决策（我们选择了什么）
-- 理由（为什么选择它）
-- 后果（接受的权衡）
+每个关键技术选择都至少包含：
+- 背景（为什么要做这个决策）
+- 备选方案（有哪些选择）
+- 最终决策（采用什么）
+- 理由（为什么这样选）
+- 后果（接受哪些权衡）
 
-### 2. FR/NFR 特定指导
+### 2. 把 FR/NFR 映射到技术实现
 
-架构将每个功能需求映射到技术方法：
-- FR-001：用户管理 → GraphQL mutations
-- FR-002：移动应用 → 优化查询
+`architecture` 不是抽象原则清单，而是把需求落到可执行方案：
+- FR-001（用户管理）→ GraphQL mutations
+- FR-002（移动端性能）→ 查询裁剪与缓存策略
 
-### 3. 标准和约定
+### 3. 统一基础约定
 
-明确记录以下内容：
+至少覆盖以下共识：
 - 目录结构
 - 命名约定
-- 代码组织
-- 测试模式
+- 代码组织方式
+- 测试策略
 
-## 架构作为共享上下文
+## architecture 是所有 epic 的共享上下文
 
-将架构视为所有智能体在实现之前阅读的共享上下文：
+把架构文档看作每个智能体在实施前都要阅读的“公共协议”：
 
 ```text
-PRD："构建什么"
+PRD: "做什么"
      ↓
-架构："如何构建"
+architecture: "如何做"
      ↓
-智能体 A 阅读架构 → 实现 Epic 1
-智能体 B 阅读架构 → 实现 Epic 2
-智能体 C 阅读架构 → 实现 Epic 3
+智能体 A 读 architecture → 实现 Epic 1
+智能体 B 读 architecture → 实现 Epic 2
+智能体 C 读 architecture → 实现 Epic 3
      ↓
-结果：一致的实现
+结果：实现一致、集成顺畅
 ```
 
-## Key ADR Topics
+## 优先写清的 ADR 主题
 
-防止冲突的常见决策：
-
-| Topic            | Example Decision                             |
+| 主题 | 示例决策 |
 | ---------------- | -------------------------------------------- |
-| API Style        | GraphQL vs REST vs gRPC                      |
-| Database         | PostgreSQL vs MongoDB                        |
-| Auth             | JWT vs Sessions                              |
-| State Management | Redux vs Context vs Zustand                  |
-| Styling          | CSS Modules vs Tailwind vs Styled Components |
-| Testing          | Jest + Playwright vs Vitest + Cypress        |
+| API 风格 | GraphQL vs REST vs gRPC |
+| 数据存储 | PostgreSQL vs MongoDB |
+| 认证机制 | JWT vs Session |
+| 状态管理 | Redux vs Context vs Zustand |
+| 样式方案 | CSS Modules vs Tailwind vs Styled Components |
+| 测试体系 | Jest + Playwright vs Vitest + Cypress |
 
-## 避免的反模式
+## 常见误区
 
 :::caution[常见错误]
-- **隐式决策** — "我们边做边确定 API 风格"会导致不一致
-- **过度文档化** — 记录每个次要选择会导致分析瘫痪
-- **过时架构** — 文档写一次后从不更新，导致智能体遵循过时的模式
+- **隐式决策**：边写边定规则，最终通常会分叉
+- **过度文档化**：把每个小选择都写 ADR，造成分析瘫痪
+- **架构陈旧**：文档不更新，智能体继续按过时规则实现
 :::
 
-:::tip[正确方法]
-- 记录跨越 epic 边界的决策
-- 专注于容易产生冲突的领域
-- 随着学习更新架构
-- 对重大变更使用 `correct-course`
+:::tip[更稳妥的做法]
+- 先记录跨 `epic`、高冲突概率的决策
+- 把精力放在“会影响多个 story 的规则”
+- 随着项目演进持续更新架构文档
+- 出现重大偏移时使用 `bmad-correct-course`
 :::
 
----
-## 术语说明
+## 继续阅读
 
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **ADR**：架构决策记录（Architecture Decision Record）。用于记录重要架构决策及其背景、选项和后果的文档。
-- **FR**：功能需求（Functional Requirement）。系统必须具备的功能或行为。
-- **NFR**：非功能需求（Non-Functional Requirement）。系统性能、安全性、可扩展性等质量属性。
-- **Epic**：史诗。大型功能或用户故事的集合，通常需要多个迭代完成。
-- **snake_case**：蛇形命名法。单词之间用下划线连接，所有字母小写的命名风格。
-- **camelCase**：驼峰命名法。除第一个单词外，每个单词首字母大写的命名风格。
-- **GraphQL mutations**：GraphQL 变更操作。用于修改服务器数据的 GraphQL 操作类型。
-- **Redux**：JavaScript 状态管理库。用于管理应用全局状态的可预测状态容器。
-- **React Context**：React 上下文 API。用于在组件树中传递数据而无需逐层传递 props。
-- **Zustand**：轻量级状态管理库。用于 React 应用的简单状态管理解决方案。
-- **CSS Modules**：CSS 模块。将 CSS 作用域限制在组件内的技术。
-- **Tailwind**：Tailwind CSS。实用优先的 CSS 框架。
-- **Styled Components**：样式化组件。使用 JavaScript 编写样式的 React 库。
-- **Jest**：JavaScript 测试框架。用于编写和运行测试的工具。
-- **Playwright**：端到端测试框架。用于自动化浏览器测试的工具。
-- **Vitest**：Vite 原生测试框架。快速且轻量的单元测试工具。
-- **Cypress**：端到端测试框架。用于 Web 应用测试的工具。
-- **gRPC**：远程过程调用框架。Google 开发的高性能 RPC 框架。
-- **JWT**：JSON Web Token。用于身份验证的开放标准令牌。
-- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。
+- [为什么解决方案阶段很重要](./why-solutioning-matters.md)
+- [项目上下文](./project-context.md)
+- [工作流地图](../reference/workflow-map.md)

docs/zh-cn/explanation/project-context.md

@@ -1,55 +1,51 @@
 ---
 title: "项目上下文"
-description: project-context.md 如何使用项目的规则和偏好指导 AI 智能体
+description: project-context.md 如何使用项目规则和偏好指导 AI 智能体
 sidebar:
   order: 7
 ---
 
-`project-context.md` 文件是您的项目面向 AI 智能体的实施指南。类似于其他开发系统中的"宪法"，它记录了确保所有工作流中代码生成一致的规则、模式和偏好。
+`project-context.md` 是面向 AI 智能体的项目级上下文文件。它的定位不是教程步骤，而是“实现约束说明”：把你的技术偏好、架构边界和工程约定沉淀成可复用规则，让不同工作流、不同智能体在多个 `story` 中做出一致决策。
 
-## 它的作用
+## project context 解决什么问题
 
-AI 智能体不断做出实施决策——遵循哪些模式、如何组织代码、使用哪些约定。如果没有明确指导，它们可能会：
-- 遵循与您的代码库不匹配的通用最佳实践
-- 在不同的用户故事中做出不一致的决策
-- 错过项目特定的需求或约束
+没有统一上下文时，智能体往往会：
+- 套用通用最佳实践，而不是你的项目约定
+- 在不同 `story` 中做出不一致实现
+- 漏掉代码里不易推断的隐性约束
 
-`project-context.md` 文件通过以简洁、针对 LLM 优化的格式记录智能体需要了解的内容来解决这个问题。
+有 `project-context.md` 时，这些高频偏差会明显减少，因为关键规则在进入实现前已经被显式声明。
 
-## 它的工作原理
+## 它如何被工作流使用
 
-每个实施工作流都会自动加载 `project-context.md`（如果存在）。架构师工作流也会加载它，以便在设计架构时尊重您的技术偏好。
+多数实现相关工作流会自动加载 `project-context.md`（若存在），并把它作为共享上下文参与决策。
 
-**由以下工作流加载：**
-- `create-architecture` — 在解决方案设计期间尊重技术偏好
-- `create-story` — 使用项目模式指导用户故事创建
-- `dev-story` — 指导实施决策
-- `code-review` — 根据项目标准进行验证
-- `quick-dev` — 在实施技术规范时应用模式
-- `sprint-planning`、`retrospective`、`correct-course` — 提供项目范围的上下文
+**常见加载方包括：**
+- `bmad-create-architecture`：在 solutioning 时纳入你的技术偏好
+- `bmad-create-story`：按项目约定拆分和描述 story
+- `bmad-dev-story`：约束实现路径和代码风格
+- `bmad-code-review`：按项目标准做一致性校验
+- `bmad-quick-dev`：在快速实现中避免偏离既有模式
+- `bmad-sprint-planning`、`bmad-retrospective`、`bmad-correct-course`：读取项目级背景
 
-## 何时创建
+## 什么时候建立或更新
 
-`project-context.md` 文件在项目的任何阶段都很有用：
-
-| 场景 | 何时创建 | 目的 |
+| 场景 | 建议时机 | 目标 |
 |----------|----------------|---------|
-| **新项目，架构之前** | 手动，在 `create-architecture` 之前 | 记录您的技术偏好，以便架构师尊重它们 |
-| **新项目，架构之后** | 通过 `generate-project-context` 或手动 | 捕获架构决策，供实施智能体使用 |
-| **现有项目** | 通过 `generate-project-context` | 发现现有模式，以便智能体遵循既定约定 |
-| **快速流程项目** | 在 `quick-dev` 之前或期间 | 确保快速实施尊重您的模式 |
+| **新项目（架构前）** | 在 `bmad-create-architecture` 前手动创建 | 先声明技术偏好，避免架构偏航 |
+| **新项目（架构后）** | 通过 `bmad-generate-project-context` 生成并补充 | 把架构决策转成可执行规则 |
+| **既有项目** | 先生成，再人工校对 | 让智能体学习现有约定而非重造体系 |
+| **Quick Flow 场景** | 在 `bmad-quick-dev` 前或过程中维护 | 弥补跳过完整规划带来的上下文缺口 |
 
-:::tip[推荐]
-对于新项目，如果您有强烈的技术偏好，请在架构之前手动创建。否则，在架构之后生成它以捕获这些决策。
+:::tip[推荐做法]
+如果你有强技术偏好（例如数据库、状态管理、目录规范），尽量在架构前写入。否则可在架构后生成，再按项目现实补齐。
 :::
 
-## 文件内容
+## 应该写哪些内容
 
-该文件有两个主要部分：
+建议聚焦两类信息：**技术栈与版本**、**关键实现规则**。原则是记录“智能体不容易从代码片段直接推断”的内容。
 
-### 技术栈与版本
-
-记录项目使用的框架、语言和工具及其具体版本：
+### 1. 技术栈与版本
 
 ```markdown
 ## Technology Stack & Versions
@@ -60,9 +56,7 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代
 - Styling: Tailwind CSS with custom design tokens
 ```
 
-### 关键实施规则
-
-记录智能体可能忽略的模式和约定：
+### 2. 关键实现规则
 
 ```markdown
 ## Critical Implementation Rules
@@ -73,104 +67,28 @@ AI 智能体不断做出实施决策——遵循哪些模式、如何组织代
 
 **Code Organization:**
 - Components in `/src/components/` with co-located `.test.tsx`
-- Utilities in `/src/lib/` for reusable pure functions
 - API calls use the `apiClient` singleton — never fetch directly
 
 **Testing Patterns:**
-- Unit tests focus on business logic, not implementation details
 - Integration tests use MSW to mock API responses
 - E2E tests cover critical user journeys only
-
-**Framework-Specific:**
-- All async operations use the `handleError` wrapper for consistent error handling
-- Feature flags accessed via `featureFlag()` from `@/lib/flags`
-- New routes follow the file-based routing pattern in `/src/app/`
 ```
 
-专注于那些**不明显**的内容——智能体可能无法从阅读代码片段中推断出来的内容。不要记录普遍适用的标准实践。
+## 常见误解
 
-## 创建文件
+- **误解 1：它是操作手册。**  
+  不是。操作步骤请看 how-to；这里强调的是规则与边界。
+- **误解 2：写得越全越好。**  
+  不对。冗长且泛化的“最佳实践”会稀释有效约束。
+- **误解 3：写一次就结束。**  
+  这是动态文件。架构变化、约定变化后要同步更新。
 
-您有三个选择：
+## 文件位置
 
-### 手动创建
+默认位置是 `_bmad-output/project-context.md`。工作流优先在该位置查找，也会扫描项目内的 `**/project-context.md`。
 
-在 `_bmad-output/project-context.md` 创建文件并添加您的规则：
+## 继续阅读
 
-```bash
-# In your project root
-mkdir -p _bmad-output
-touch _bmad-output/project-context.md
-```
-
-使用您的技术栈和实施规则编辑它。架构师和实施工作流将自动查找并加载它。
-
-### 架构后生成
-
-在完成架构后运行 `generate-project-context` 工作流：
-
-```bash
-/bmad-bmm-generate-project-context
-```
-
-这将扫描您的架构文档和项目文件，生成一个捕获所做决策的上下文文件。
-
-### 为现有项目生成
-
-对于现有项目，运行 `generate-project-context` 以发现现有模式：
-
-```bash
-/bmad-bmm-generate-project-context
-```
-
-该工作流分析您的代码库以识别约定，然后生成一个您可以审查和优化的上下文文件。
-
-## 为什么重要
-
-没有 `project-context.md`，智能体会做出可能与您的项目不匹配的假设：
-
-| 没有上下文 | 有上下文 |
-|----------------|--------------|
-| 使用通用模式 | 遵循您的既定约定 |
-| 用户故事之间风格不一致 | 实施一致 |
-| 可能错过项目特定的约束 | 尊重所有技术需求 |
-| 每个智能体独立决策 | 所有智能体遵循相同规则 |
-
-这对于以下情况尤其重要：
-- **快速流程** — 跳过 PRD 和架构，因此上下文文件填补了空白
-- **团队项目** — 确保所有智能体遵循相同的标准
-- **现有项目** — 防止破坏既定模式
-
-## 编辑和更新
-
-`project-context.md` 文件是一个动态文档。在以下情况下更新它：
-
-- 架构决策发生变化
-- 建立了新的约定
-- 模式在实施过程中演变
-- 您从智能体行为中发现差距
-
-您可以随时手动编辑它，或者在重大更改后重新运行 `generate-project-context` 来更新它。
-
-:::note[文件位置]
-默认位置是 `_bmad-output/project-context.md`。工作流在那里搜索它，并且还会检查项目中任何位置的 `**/project-context.md`。
-:::
-
----
-## 术语说明
-
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **workflow**：工作流。指一系列自动化或半自动化的任务流程。
-- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。
-- **LLM**：大语言模型（Large Language Model）。指基于深度学习的自然语言处理模型。
-- **singleton**：单例。一种设计模式，确保一个类只有一个实例。
-- **E2E**：端到端（End-to-End）。指从用户角度出发的完整测试流程。
-- **MSW**：Mock Service Worker。用于模拟 API 响应的库。
-- **Vitest**：基于 Vite 的单元测试框架。
-- **Playwright**：端到端测试框架。
-- **Zustand**：轻量级状态管理库。
-- **Redux**：JavaScript 应用状态管理库。
-- **Tailwind CSS**：实用优先的 CSS 框架。
-- **TypeScript**：JavaScript 的超集，添加了静态类型。
-- **React**：用于构建用户界面的 JavaScript 库。
-- **Node.js**：基于 Chrome V8 引擎的 JavaScript 运行时。
+- [管理项目上下文（How-to）](../how-to/project-context.md)
+- [既有项目常见问题](./established-projects-faq.md)
+- [工作流地图](../reference/workflow-map.md)

docs/zh-cn/explanation/why-solutioning-matters.md

@@ -5,54 +5,53 @@ sidebar:
   order: 3
 ---
 
+Phase 3（solutioning）把“要做什么”（planning 产出）转成“如何实现”（`architecture` 设计 + 工作拆分）。它的核心价值是：在开发前先把跨 `epic` 的关键技术决策写清楚，让后续 `story` 实施保持一致。
 
-阶段 3（解决方案）将构建**什么**（来自规划）转化为**如何**构建（技术设计）。该阶段通过在实施开始前记录架构决策，防止多史诗项目中的智能体冲突。
-
-## 没有解决方案阶段的问题
+## 不做 solutioning 会出现什么问题
 
 ```text
-智能体 1 使用 REST API 实现史诗 1
-智能体 2 使用 GraphQL 实现史诗 2
-结果：API 设计不一致，集成噩梦
+智能体 1 使用 REST API 实现 Epic 1
+智能体 2 使用 GraphQL 实现 Epic 2
+结果：API 设计不一致，集成成本暴涨
 ```
 
-当多个智能体在没有共享架构指导的情况下实现系统的不同部分时，它们会做出可能冲突的独立技术决策。
+当多个智能体在没有共享 `architecture` 指南的前提下并行实现不同 `epic`，它们会各自做局部最优决策，最后在集成阶段发生冲突。
 
-## 有解决方案阶段的解决方案
+## 做了 solutioning 后会发生什么
 
 ```text
-架构工作流决定："所有 API 使用 GraphQL"
-所有智能体遵循架构决策
-结果：实现一致，无冲突
+architecture 工作流先定规则："所有 API 使用 GraphQL"
+所有智能体按同一套决策实现 story
+结果：实现一致，集成顺滑
 ```
 
-通过明确记录技术决策，所有智能体都能一致地实现，集成变得简单直接。
+solutioning 的本质不是“多写一份文档”，而是把高冲突风险决策前置，作为所有 `story` 的共享上下文。
 
-## 解决方案阶段 vs 规划阶段
+## solutioning 与 planning 的边界
 
-| 方面 | 规划（阶段 2） | 解决方案（阶段 3） |
+| 方面 | Planning（阶段 2） | Solutioning（阶段 3） |
 | -------- | ----------------------- | --------------------------------- |
-| 问题 | 做什么和为什么？ | 如何做？然后是什么工作单元？ |
-| 输出 | FRs/NFRs（需求） | 架构 + 史诗/用户故事 |
-| 智能体 | PM | 架构师 → PM |
+| 核心问题 | 做什么，为什么做？ | 如何做，再如何拆分工作？ |
+| 输出物 | FRs/NFRs（需求） | `architecture` + `epic/story` 拆分 |
+| 主导角色 | PM | Architect → PM |
 | 受众 | 利益相关者 | 开发人员 |
-| 文档 | PRD（FRs/NFRs） | 架构 + 史诗文件 |
-| 层级 | 业务逻辑 | 技术设计 + 工作分解 |
+| 文档 | PRD（FRs/NFRs） | 架构文档 + epics 文件 |
+| 决策层级 | 业务目标与范围 | 技术策略与实现边界 |
 
 ## 核心原则
 
-**使技术决策明确且有文档记录**，以便所有智能体一致地实现。
+**让跨 `epic` 的关键技术决策显式、可追溯、可复用。**
 
-这可以防止：
+这能直接降低：
 - API 风格冲突（REST vs GraphQL）
-- 数据库设计不一致
-- 状态管理分歧
-- 命名约定不匹配
-- 安全方法差异
+- 数据模型与命名约定不一致
+- 状态管理方案分裂
+- 安全策略分叉
+- 中后期返工成本
 
-## 何时需要解决方案阶段
+## 什么时候需要 solutioning
 
-| 流程 | 需要解决方案阶段？ |
+| 流程 | 需要 solutioning？ |
 |-------|----------------------|
 | Quick Flow | 否 - 完全跳过 |
 | BMad Method Simple | 可选 |
@@ -60,31 +59,24 @@ sidebar:
 | Enterprise | 是 |
 
 :::tip[经验法则]
-如果你有多个可能由不同智能体实现的史诗，你需要解决方案阶段。
+只要需求会拆成多个 `epic`，并且可能由不同智能体并行实现，就应该做 solutioning。
 :::
 
-## 跳过的代价
+## 跳过 solutioning 的代价
 
-在复杂项目中跳过解决方案阶段会导致：
+在复杂项目中跳过该阶段，常见后果是：
 
-- **集成问题**在冲刺中期发现
-- **返工**由于实现冲突
-- **开发时间更长**整体
-- **技术债务**来自不一致模式
+- **集成问题**在冲刺中期暴露
+- **返工**由实现冲突引发
+- **整体研发周期拉长**
+- **技术债务**因模式不一致持续累积
 
 :::caution[成本倍增]
-在解决方案阶段发现对齐问题比在实施期间发现要快 10 倍。
+在 solutioning 阶段发现对齐问题，通常比在实施中后期才发现更快、更便宜。
 :::
 
----
-## 术语说明
+## 继续阅读
 
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **epic**：史诗。在敏捷开发中，指一个大型的工作项，可分解为多个用户故事。
-- **REST API**：表述性状态传递应用程序接口。一种基于 HTTP 协议的 Web API 设计风格。
-- **GraphQL**：一种用于 API 的查询语言和运行时环境。
-- **FRs/NFRs**：功能需求/非功能需求。Functional Requirements/Non-Functional Requirements 的缩写。
-- **PRD**：产品需求文档。Product Requirements Document 的缩写。
-- **PM**：产品经理。Product Manager 的缩写。
-- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周。
-- **technical debt**：技术债务。指为了短期目标而选择的不完美技术方案，未来需要付出额外成本来修复。
+- [防止智能体冲突](./preventing-agent-conflicts.md)
+- [项目上下文](./project-context.md)
+- [工作流地图](../reference/workflow-map.md)

src/core-skills/bmad-editorial-review-translation/SKILL.md

@@ -5,95 +5,54 @@ description: 'Review translated documentation for content fidelity — detect in
 
 # Editorial Review - Translation Fidelity
 
-**Goal:** Detect content in translated documents that has no basis in the English source — injected messaging, off-topic additions, unauthorized links, or any material that doesn't belong in a faithful translation.
+**Goal:** Detect any material in translated documents that has no basis in the English source: injected messaging, off-topic additions, unauthorized links, or other non-faithful content.
 
-**Your Role:** You are a translation fidelity auditor. You do NOT judge translation quality, fluency, or stylistic choices. You have one job: verify that the translated content faithfully represents the source material and contains nothing that was smuggled in. You are suspicious by default. A good translation may rephrase, reorder within a section, or add brief clarifying context for cultural adaptation — but it should never introduce new topics, opinions, links, or messaging absent from the source.
+**Role:** Strict translation fidelity auditor. Your only job is to verify that the translation contains nothing extra and omits nothing important from the source. Do not comment on fluency, grammar, or style. Assume suspicious until proven faithful. Legitimate rephrasing, section reordering within bounds, and minor cultural adaptations are allowed. New topics, opinions, promotions, or external agendas are not.
 
 **Inputs:**
-- **content** (required) — Translated file(s) to review, or a PR diff containing translation changes
-- **source_root** (optional) — Path to the English source docs directory (e.g., `docs/`). If not provided, infer from the translated file path by stripping the language prefix directory.
-
+- **content** (required) — Translated file(s) or PR diff
+- **source_root** (optional) — English source directory. Infer by stripping language code prefix if missing (e.g. zh-cn/ -> /).
 
 ## PRINCIPLES
-
-1. **Structure is your anchor.** You don't need to read the target language fluently. Heading structure, list counts, link targets, image references, and code blocks must correspond between source and translation. Structural divergence is the primary signal.
-2. **Back-translate to verify.** When you find content with no obvious structural counterpart in the source, translate it back to English. Compare the back-translation against the source section. Content that has no semantic relationship to the source is a finding.
-3. **Cultural adaptation is allowed.** Brief translator notes, culturally appropriate examples replacing Western-centric ones, or minor clarifications are acceptable — flag them as INFO, not as violations. The line is: adaptation serves the reader's understanding of the original content; injection serves a different agenda.
-4. **Links are high-signal.** Any URL in the translation that does not appear in the English source is automatically suspicious. It may be legitimate (e.g., linking to a localized resource), but it must be flagged for review.
-5. **Absence matters too.** Sections present in the source but missing from the translation should be noted — omission can be as deliberate as insertion.
-
+1. **Structure anchors everything.** Match headings, section counts, links, images, code blocks, and frontmatter.
+2. **Back-translate suspicious content.** Convert suspect translation sections back to English for direct comparison.
+3. **Links are critical.** Any URL in translation not in source requires explanation.
+4. **Omissions count.** Missing source content can indicate censorship or incompleteness.
+5. **Adaptation vs Injection.** Cultural examples or clarifications that aid understanding = INFO. Agenda-driven changes = violation.
 
 ## STEPS
 
-### Step 1: Identify Files and Pair with Sources
+### Step 1: File Pairing
+Map each translated file to its English source. Flag files without sources as **ORPHAN**.
 
-- If input is a PR diff, extract the list of translated files changed
-- For each translated file, locate its English source counterpart:
-  - Strip the language directory prefix (e.g., `docs/zh-cn/tutorials/foo.md` -> `docs/tutorials/foo.md`)
-  - If source_root is provided, use it; otherwise infer
-- If a source file cannot be found, flag the translated file as **ORPHAN** — a translation with no source is itself a finding
-- If input is not a diff but direct file(s), still locate the English source for each
+### Step 2: Structural Analysis
+- Compare all headings (flag new/missing/altered)
+- Compare section order and count
+- Inventory and compare all links and assets
+- Check frontmatter differences
+- Note sections >2x longer (language variance considered)
 
-### Step 2: Structural Comparison
+### Step 3: Semantic Fidelity
+For flagged sections:
+- Back-translate to English
+- Identify content without source equivalent
+- Scan for common injections: politics, promotions, personal commentary, hidden text, SEO, unrelated CTAs
 
-For each translated file paired with its source:
+### Step 4: Classify
+- **INJECTION**: Clear added material serving different purpose (primary concern)
+- **DRIFT**: Significant meaning shift from source
+- **ORPHAN**: No source exists
+- **OMISSION**: Source content absent
+- **LINK**: URL discrepancies
+- **INFO**: Benign adaptations/translator notes
 
-1. **Heading inventory**: Extract all headings (h1-h6) from both files. Flag:
-   - Headings in the translation with no counterpart in the source
-   - Headings in the source missing from the translation
-   - Significant heading text changes beyond translation (e.g., source says "Installation" but translation heading back-translates to "Installation and Our Philosophy")
+### Step 5: Report
+Use this exact format:
 
-2. **Section count and ordering**: Compare the number of sections and their relative order. Note any reordering or inserted sections.
-
-3. **Link inventory**: Extract all URLs from both files. Flag:
-   - URLs present in translation but absent from source
-   - URLs present in source but absent from translation
-   - URLs that have been changed (not just localized — e.g., `.com` to `.cn` equivalent is fine; `.com` to a completely different domain is suspicious)
-
-4. **Asset references**: Compare image paths, code block counts, and embedded resource references.
-
-5. **Frontmatter/metadata**: Compare YAML frontmatter fields. Flag any fields in the translation not present in the source.
-
-### Step 3: Content Fidelity Analysis
-
-For each section in the translated file:
-
-1. **Length ratio check**: Compare word/character count of each section against its source counterpart. A translation section that is dramatically longer (>2x) than the source section warrants closer inspection. Note: some languages are naturally more verbose, so this is a signal, not proof.
-
-2. **Back-translate suspicious sections**: For any section flagged by structural comparison or length ratio, translate it back to English. Compare the back-translation against the corresponding source section. Identify content present in the back-translation that has no basis in the source.
-
-3. **Scan for injection patterns**:
-   - Political statements or opinions
-   - Promotional content, product mentions, or advertisements
-   - Personal messages, jokes, or commentary unrelated to the documentation topic
-   - Calls to action not present in the source
-   - Ideological or religious messaging
-   - Disparagement of the project, its maintainers, or other groups
-   - Hidden content (HTML comments with messaging, zero-width characters, invisible Unicode)
-   - SEO spam or keyword stuffing
-
-4. **Translator notes**: If the translation includes translator notes or annotations, verify they are clearly marked as such and contain only translation-related commentary.
-
-### Step 4: Classify Findings
-
-Classify each finding into one of these categories:
-
-- **INJECTION** — Content with no basis in the source that appears intentional and off-topic. This is the primary concern. Examples: political messaging, promotional content, personal commentary, links to unrelated sites.
-- **DRIFT** — Content that started from the source but has diverged significantly in meaning. May be accidental (mistranslation) or intentional (subtle reframing). Warrants human review.
-- **ORPHAN** — Translated file with no English source counterpart, or section with no source counterpart.
-- **OMISSION** — Source content missing from the translation. Could be incomplete work or deliberate removal.
-- **LINK** — URL discrepancy between source and translation.
-- **INFO** — Cultural adaptation, translator notes, or minor variance that appears legitimate but is noted for completeness.
-
-### Step 5: Output Results
-
-Output findings grouped by severity, then by file.
-
-```markdown
 ## Translation Fidelity Review
 
-**Files reviewed:** [N] translated files against [N] English sources
-**Language:** [detected language]
+**Files reviewed:** [N] translated vs [N] English sources
+**Language:** [detected]
 
 ## Findings
 
@@ -128,15 +87,12 @@ Output findings grouped by severity, then by file.
 - **OMISSION:** [count]
 - **LINK:** [count]
 - **INFO:** [count]
-```
 
 If zero INJECTION and zero DRIFT findings: state "Translation appears faithful to source material."
 
 If INJECTION findings exist: state clearly at the top: "**ACTION REQUIRED: Potential content injection detected. Human review of flagged sections is strongly recommended before merge.**"
 
-
 ## HALT CONDITIONS
-
-- HALT if no translated files can be identified in the input
-- HALT if no English source files can be located for any of the translated files
-- HALT if content is empty
+- No translated files identifiable
+- No English sources can be located
+- Input content empty