Skip to content

docs(zh-cn): refine Epic3 story 3.3 and 3.4 explanations#2099

Merged
alexeyv merged 2 commits intobmad-code-org:mainfrom
lrliang:docs/e3s3-s3s4-cn-explanation
Mar 24, 2026
Merged

docs(zh-cn): refine Epic3 story 3.3 and 3.4 explanations#2099
alexeyv merged 2 commits intobmad-code-org:mainfrom
lrliang:docs/e3s3-s3s4-cn-explanation

Conversation

@lrliang
Copy link
Copy Markdown
Contributor

@lrliang lrliang commented Mar 22, 2026

What

This PR updates five Chinese explanation pages for Epic 3 Story 3.3 and Story 3.4: docs/zh-cn/explanation/brainstorming.md, docs/zh-cn/explanation/advanced-elicitation.md, docs/zh-cn/explanation/party-mode.md, docs/zh-cn/explanation/quick-dev.md, and docs/zh-cn/explanation/adversarial-review.md. It clarifies mode positioning, usage boundaries, and value differences, while keeping workflow naming and internal links aligned with current conventions.

本次 PR 修订了 Epic 3 的 Story 3.3 与 Story 3.4 对应的 5 篇中文 explanation 文档:docs/zh-cn/explanation/brainstorming.mddocs/zh-cn/explanation/advanced-elicitation.mddocs/zh-cn/explanation/party-mode.mddocs/zh-cn/explanation/quick-dev.mddocs/zh-cn/explanation/adversarial-review.md。重点是澄清各模式定位、使用边界与价值差异,并保持工作流命名和内部跳转与当前约定一致。

Why

The previous Chinese pages still had literal-translation traces and blurred boundaries between adjacent modes (brainstorming vs advanced elicitation vs party mode, and quick dev vs adversarial review), which could lead to mode misuse. This change improves conceptual clarity and operational guidance while preserving semantic parity with the English source.

现有中文页面仍存在直译痕迹,且相邻模式边界不够清晰(如 brainstorming / advanced elicitation / party mode,以及 quick dev / adversarial review),容易导致选型和使用误判。该改动用于提升概念清晰度与操作指引性,并保持与英文源文语义对齐。

How

  • Rewrote Story 3.3 pages to explicitly explain what each collaboration mode is, when to use it, and how it differs from nearby alternatives.
  • Reframed Story 3.4 pages around practical positioning: Quick Dev as execution cadence design and Adversarial Review as issue-finding/review strategy.
  • Standardized key terms and workflow references (e.g. bmad-brainstorming, bmad-party-mode, bmad-quick-dev) and ensured Chinese-first related links.
  • Removed glossary-style tails so these explanation docs stay focused on conceptual understanding and decision boundaries.
  • 重写 Story 3.3 三篇文档,显式说明各协作模式“是什么、何时用、与邻近模式如何区分”。
  • 重构 Story 3.4 两篇文档定位:将 Quick Dev 明确为执行节奏设计,将对抗性评审明确为问题发现与评审分诊策略。
  • 统一关键术语与 workflow 引用(如 bmad-brainstormingbmad-party-modebmad-quick-dev),并确保中文优先关联跳转。
  • 清理术语附录式尾段,让 explanation 文档聚焦概念理解与决策边界。

Testing

Ran npm ci && npm run quality successfully. This includes format checks, linting, markdown linting, docs build, installation component tests, reference validation, and skill validation.

已执行 npm ci && npm run quality,检查通过。该流程覆盖格式检查、lint、markdown lint、文档构建、安装组件测试、引用校验与技能校验。

Made with Cursor

@augmentcode
Copy link
Copy Markdown

augmentcode bot commented Mar 22, 2026

🤖 Augment PR Summary

Summary: This PR refines the Chinese “Explanation” docs for Epic 3 Story 3.3–3.4 to make collaboration modes and review modes easier to choose and apply.

Changes:

  • Rewrote brainstorming, advanced elicitation, and party mode explanations to clarify what each mode is, when to use it, and where it should not be used.
  • Reframed quick dev as an execution-cadence/guardrails workflow and adversarial review as an issue-finding + triage strategy.
  • Added side-by-side comparison tables to distinguish adjacent modes and reduce misuse.
  • Standardized terminology, workflow mentions, and “continue reading” cross-links across the five pages.
  • Removed glossary-style tail sections so the pages focus on decision boundaries and practical guidance.

Technical Notes: The PR is documentation-only and is intended to improve conceptual clarity while staying aligned with current workflow naming and internal link conventions.

🤖 Was this summary useful? React with 👍 or 👎

Copy link
Copy Markdown

@augmentcode augmentcode bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review completed. 2 suggestions posted.

Fix All in Augment

Comment augment review to trigger a new review at any time.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 22, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b25c5b05-92a3-4e68-92a8-13dcdf25775f

📥 Commits

Reviewing files that changed from the base of the PR and between e3f935f and 8f6d502.

📒 Files selected for processing (5)
  • docs/zh-cn/explanation/advanced-elicitation.md
  • docs/zh-cn/explanation/adversarial-review.md
  • docs/zh-cn/explanation/brainstorming.md
  • docs/zh-cn/explanation/party-mode.md
  • docs/zh-cn/explanation/quick-dev.md

📝 Walkthrough

Walkthrough

This PR rewrites documentation for five Chinese language explanation documents covering BMAD methodology features: advanced elicitation, adversarial review, brainstorming, party mode, and quick dev. Changes restructure content around consistent sections including use-case guidance, limitations, comparison tables with related modes, and cross-references.

Changes

Cohort / File(s) Summary
Advanced Elicitation & Adversarial Review
docs/zh-cn/explanation/advanced-elicitation.md, docs/zh-cn/explanation/adversarial-review.md
Reframed conceptual descriptions; replaced detailed method/terminology lists with higher-level workflow explanations. Added comparison tables with other modes, explicit boundaries/limitations sections, and "继续阅读" cross-references. Removed glossaries.
Brainstorming & Party Mode
docs/zh-cn/explanation/brainstorming.md, docs/zh-cn/explanation/party-mode.md
Replaced generic descriptions with workflow-focused explanations. Added "什么时候使用" and "不适合的场景" sections; restructured process descriptions. Introduced comparison tables linking modes and added internal cross-references.
Quick Dev
docs/zh-cn/explanation/quick-dev.md
Rewrote to emphasize problem statement and five-step core mechanism. Removed detailed design/failure-mode discussions; added explicit applicability boundaries, practical advice callout, and updated relationship description to adversarial review.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Suggested reviewers

  • bmadcode
  • alexeyv
🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: refining Chinese explanation documentation for Epic 3 stories 3.3 and 3.4, which directly corresponds to the five files modified in the changeset.
Description check ✅ Passed The description is comprehensive and directly related to the changeset, explaining the what/why/how of the updates to the five Chinese documentation files with concrete examples of improvements made.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Tip

CodeRabbit can use oxc to improve the quality of JavaScript and TypeScript code reviews.

Add a configuration file to your project to customize how CodeRabbit runs oxc.

@cccczl
Copy link
Copy Markdown
Contributor

cccczl commented Mar 23, 2026

Already fully checked, please @alexeyv merge.

leon added 2 commits March 23, 2026 20:06
我重写头脑风暴、高级启发与 Party Mode 的中文说明,明确三者在适用场景、价值和边界上的差异,避免字面对译带来的误用。
我同步收敛 Quick Dev 与对抗性评审文案,强调各自定位与配合关系,并补齐中文优先链路和当前 workflow 命名。

feishu: https://feishu.cn/wiki/TODO
Made-with: Cursor
我将五篇 explanation 文档里的四冒号提示块语法统一为三冒号,确保与当前文档渲染规则一致。
此前这些文档混用不同围栏写法,容易在审阅和渲染中引入不必要差异;现在统一后可减少维护噪音。

feishu: https://feishu.cn/wiki/TODO
Made-with: Cursor
@alexeyv alexeyv force-pushed the docs/e3s3-s3s4-cn-explanation branch from 3e71583 to 7337aea Compare March 24, 2026 02:40
@alexeyv alexeyv merged commit 94831cb into bmad-code-org:main Mar 24, 2026
5 checks passed
@lrliang lrliang deleted the docs/e3s3-s3s4-cn-explanation branch March 24, 2026 08:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants