在准备发布、同步文档或创建 PR 前，根据 Git…

分析当前分支相对最近 release tag 的 git 变更，并更新 README.md、CHANGELOG.md 及相关文档文件夹。

适用场景

解决思路

1. 用 `git rev-parse --git-dir` 确认处于 git 仓库；用 `git tag --list | head -5` 检查是否存在 git tag；用 `test -f README.md || echo "README.md not found"` 和 `test -f CHANGELOG.md || echo "CHANGELOG.md not found"` 检查文档文件；若没有 tag，告诉用户至少需要一个 release tag 才能比较。
2. Phase 1：用 `LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)` 检测最新 release tag；若 `LATEST_TAG` 为空，输出没有 git tag、需要先创建 release tag（例如 `git tag -a v1.0.0 -m 'Initial release'`）并退出。
3. Phase 1：用 `CURRENT_BRANCH=$(git branch --show-current)` 获取当前分支；用 `VERSION=$(echo "$LATEST_TAG" | sed -E 's/^[^0-9]*([0-9]+\.[0-9]+\.[0-9]+).*/\1/')` 解析版本号；显示最新 tag、检测到的版本和比较范围 `LATEST_TAG -> CURRENT_BRANCH`。
4. Phase 2：用 `COMMIT_COUNT=$(git rev-list --count ${LATEST_TAG}..HEAD 2>/dev/null || echo "0")` 获取 tag 到 HEAD 的提交数，并显示自 `$LATEST_TAG` 以来的提交数。
5. Phase 2：用 `git diff --stat ${LATEST_TAG}..HEAD` 获取文件变更统计。
6. Phase 2：用 `COMMITS=$(git log ${LATEST_TAG}..HEAD --pretty=format:"%h|%s|%b" --reverse)` 提取提交消息，并输出供审查。
7. Phase 2：用 `CHANGED_FILES=$(git diff --name-only ${LATEST_TAG}..HEAD)` 获取变更文件列表。
8. Phase 2：用 `git diff --name-status ${LATEST_TAG}..HEAD` 显示新增/修改/删除状态，便于快速分类。
9. Phase 2：用 `echo "$CHANGED_FILES" | grep -E "^plugins/" | cut -d'/' -f2 | sort -u` 按文件路径识别变更的组件/区域。
10. Phase 3：检查常见文档目录：存在则把 `docs/`、`documentation/`、`doc/` 加入 `DOC_FOLDERS`（分别用 `[ -d "docs" ]`、`[ -d "documentation" ]`、`[ -d "doc" ]` 判断）。
11. Phase 3：遍历 `plugins/*/`，若存在 `${plugin_dir}docs`，把 `${plugin_dir}docs/` 加入 `DOC_FOLDERS`；输出找到的文档文件夹。
12. Phase 3：检查并收集标准文档文件到 `DOC_FILES`：`README.md`、`CHANGELOG.md`、`CONTRIBUTING.md`、`docs/GUIDE.md`；输出找到的文档文件。
13. Phase 4：解析提交消息，按 conventional commit 语义映射到 Keep a Changelog 章节，如 `Added`、`Changed`、`Fixed`、`Removed`、`Security`。
14. Phase 4：读取现有 `CHANGELOG.md` 理解结构，然后按 Keep a Changelog 格式生成新条目；详细 bash 命令和 changelog 模板见 `references/examples.md`。
15. Phase 5：读取当前 `README.md` 理解其结构。
16. Phase 5：识别需要更新的章节，例如 features list、skills/agents、setup instructions、version references。
17. Phase 5：用 Edit 工具应用更新：保留结构、保持语气、更新版本号。
18. Phase 6：对每个发现的文档文件夹，检查其中引用已变更代码的文件。
19. Phase 6：将变更文件映射到对应文档。
20. Phase 6：生成更新：添加新功能文档、更新 API references、修复过时示例；详细发现模式和更新策略见 `references/examples.md`。
21. Phase 7：展示拟议变更摘要，包含 Version Information（Previous release、Current branch、Commits analyzed）、Files to Update（CHANGELOG.md、README.md、docs/[specific files] 及对应说明）、Summary of Changes（Added/Changed/Fixed/Breaking 的数量）。
22. Phase 7：用 **AskUserQuestion** 询问用户：确认要更新哪些文件、是否有变更需要修改、获取继续执行的批准。
23. Phase 8：更新 `CHANGELOG.md`：读取当前 changelog，按模板前置新章节，包含 `[Unreleased]`、Keep a Changelog 链接、Semantic Versioning 链接，并保留现有 changelog 内容。
24. Phase 8：用 Edit 工具更新 `README.md`：只做针对特定章节的编辑，保留整体结构，必要时更新版本号。
25. Phase 8：对每个需要更新的文档文件，用 Edit 工具做精确修改。
26. Phase 8：验证应用后的变更：`test -f CHANGELOG.md && echo "CHANGELOG.md present"`、`test -f README.md && echo "README.md present"`。
27. Phase 8：查看 markdown 变更范围：`git diff --stat -- '*.md'`。
28. Phase 8：抽查实际写入内容：`git diff -- '*.md' | sed -n '1,240p'`。
29. Phase 8：如果仓库已定义文档或 markdown 验证命令，在结束前运行它们。
30. Best Practice：写前预览、写后验证：先展示计划，再确认最终 diff。
31. Best Practice：遵循 Keep a Changelog，保持 changelog 格式一致。
32. Best Practice：正确分类，使用正确类别（Added、Changed、Fixed 等）。
33. Best Practice：具体明确，在 changelog 条目中包含 plugin/component 名称。
34. Best Practice：保留结构，维持现有文档结构和风格。
35. Best Practice：在有用时引用 commit hash 以便追溯。
36. Best Practice：处理 breaking changes，用迁移说明清晰突出。
37. Best Practice：更新版本引用，保持文档中的版本号一致。
38. 生成的 changelog 条目需要人工审查准确性。
39. 所有文件路径使用正斜杠（Unix 风格）以保证跨平台兼容。

适用边界 · 注意事项

• 仓库没有任何 release tag 时不适用；该技能需要至少一个 tag 作为比较基线。
• 需要自动创建 release tag 或自动提交文档变更时不适用；该技能只准备文档变更，不创建 tag、不自动 commit。
• 项目使用无法按 Keep a Changelog 调整的自定义 changelog 格式，或提交记录完全不遵循 conventional commit 且无法人工归类时，应谨慎使用或先人工整理。