Back to Details

living-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Living Docs

活文档

Generate documentation driven by actual code changes. Every document traces to specific commits and files. When code changes, docs change.
Language policy: Generate all documentation in English. Include Spanish translations in the 
aliases
frontmatter field.
基于实际代码变更驱动生成文档，每份文档都可追溯到特定提交和文件，代码变更时文档同步更新。
语言政策：所有文档默认使用英文生成，西班牙语翻译需放在
aliases
元数据字段中。

Activation Signals

触发条件

Use this skill immediately when the user intent matches documentation-from-code-changes.
High-confidence trigger phrases (English/Spanish):
  • "document this feature", "document X functionality", "document current branch"
  • "document the diff", "what changed", "generate release notes", "generate changelog"
  • "update docs for react/integrator/magento", "document all microservices"
  • "documenta esta funcionalidad", "documenta la branch actual", "analiza el diff y genera documentacion"
Intent-to-scope defaults:
  • "document this feature/funcionalidad" -> current branch vs default branch
  • "document current branch/branch actual" -> current branch vs default branch
  • "release notes/changelog" -> last N commits (default 20 unless user specifies)
  • "what changed" -> branch diff first; fall back to last N commits if branch base is unclear
Do not trigger this skill for generic writing requests not tied to git changes.
当用户意图匹配「基于代码变更生成文档」时可立即使用本技能。
高置信触发短语（英文/西班牙文）：
  • "document this feature", "document X functionality", "document current branch"
  • "document the diff", "what changed", "generate release notes", "generate changelog"
  • "update docs for react/integrator/magento", "document all microservices"
  • "documenta esta funcionalidad", "documenta la branch actual", "analiza el diff y genera documentacion"
意图对应默认范围：
  • "document this feature/funcionalidad" → 当前分支与默认分支对比
  • "document current branch/branch actual" → 当前分支与默认分支对比
  • "release notes/changelog" → 最近N次提交（默认20次，用户另有指定除外）
  • "what changed" → 优先对比分支差异；如果分支基准不明确，则回退到最近N次提交
通用写作请求如果和git变更无关，不要触发本技能。

Folder Structure

文件夹结构

This skill supports a two-phase documentation workflow for microservice architectures:
本技能支持微服务架构的两阶段文档工作流：

Phase 1: Local Development (per microservice)

阶段1：本地开发（单微服务维度）

Generate docs in the 
docs/
folder of each microservice during feature development. Keep the folder structure but use the naming convention:
<repo-root>/
├── react/
│   └── docs/
│       ├── components/          # Component Docs
│       │   ├── react_comp_auth.md
│       │   └── react_comp_user_service.md
│       ├── changelogs/         # Changelogs and release notes
│       │   └── react_cl_2026-02-28.md
│       ├── adrs/               # Architecture Decision Records
│       │   └── react_adr_001_oauth.md
│       ├── runbooks/           # Runbooks and SOPs
│       │   └── react_rb_deploy.md
│       ├── guides/             # User Guides (NEW)
│       │   └── react_guide_oauth_setup.md
│       ├── technical/          # Technical Guides (NEW)
│       │   └── react_tech_state_mgmt.md
│       ├── bugs/               # Bug Reports (NEW)
│       │   └── react_bug_auth_timeout.md
│       ├── plans/              # Plans (NEW)
│       │   └── react_plan_q2_migration.md
│       ├── tasks/              # Task Docs (NEW)
│       │   └── react_task_deps_update.md
│       └── index.md            # Auto-generated index linking all docs
├── integrator/
│   └── docs/
│       └── ...
└── ...
功能开发过程中在每个微服务的
docs/
文件夹下生成文档，保持如下文件夹结构，遵循对应命名规范：
<repo-root>/
├── react/
│   └── docs/
│       ├── components/          # 组件文档
│       │   ├── react_comp_auth.md
│       │   └── react_comp_user_service.md
│       ├── changelogs/         # 变更日志与发布说明
│       │   └── react_cl_2026-02-28.md
│       ├── adrs/               # 架构决策记录
│       │   └── react_adr_001_oauth.md
│       ├── runbooks/           # 运行手册与标准操作流程
│       │   └── react_rb_deploy.md
│       ├── guides/             # 用户指南（新增）
│       │   └── react_guide_oauth_setup.md
│       ├── technical/          # 技术指南（新增）
│       │   └── react_tech_state_mgmt.md
│       ├── bugs/               # Bug报告（新增）
│       │   └── react_bug_auth_timeout.md
│       ├── plans/              # 计划（新增）
│       │   └── react_plan_q2_migration.md
│       ├── tasks/              # 任务文档（新增）
│       │   └── react_task_deps_update.md
│       └── index.md            # 自动生成的索引，关联所有文档
├── integrator/
│   └── docs/
│       └── ...
└── ...

Phase 2: Centralized (docs-microservices)

阶段2：集中化管理（docs-microservices）

After PR approval, merge docs to 
docs-microservices/
:
docs-microservices/
├── reference/     # Component Docs, Guides, Technical Docs (from components/, guides/, technical/)
│   ├── react/
│   ├── integrator/
│   └── ...
├── engineering/   # ADRs, Runbooks (from adrs/, runbooks/)
│   ├── adrs/
│   └── runbooks/
├── reports/       # Changelogs, Bug Reports (from changelogs/, bugs/)
│   └── changelogs/
└── strategy/     # Plans (from plans/)
    └── ...
PR获批后，将文档合并到
docs-microservices/
仓库：
docs-microservices/
├── reference/     # 组件文档、指南、技术文档（来自components/、guides/、technical/）
│   ├── react/
│   ├── integrator/
│   └── ...
├── engineering/   # ADR、运行手册（来自adrs/、runbooks/）
│   ├── adrs/
│   └── runbooks/
├── reports/       # 变更日志、Bug报告（来自changelogs/、bugs/）
│   └── changelogs/
└── strategy/     # 计划（来自plans/）
    └── ...

File Naming Conventions

文件命名规范

Pattern: 
${REPO}_${TYPE_CODE}_${SLUG}.md
Doc TypeFolderType CodeFilename PatternExample
Component Doc
docs/components/
comp
{repo}_comp_{name}.md
react_comp_auth.md
Changelog
docs/changelogs/
cl
{repo}_cl_{YYYY-MM-DD}.md
react_cl_2026-02-28.md
ADR
docs/adrs/
adr
{repo}_adr_{NNN}_{slug}.md
react_adr_001_oauth.md
Runbook
docs/runbooks/
rb
{repo}_rb_{operation}.md
react_rb_deploy.md
Guide
docs/guides/
guide
{repo}_guide_{topic}.md
react_guide_oauth_setup.md
Technical
docs/technical/
tech
{repo}_tech_{topic}.md
react_tech_state_mgmt.md
Bug Report
docs/bugs/
bug
{repo}_bug_{issue}.md
react_bug_auth_timeout.md
Plan
docs/plans/
plan
{repo}_plan_{initiative}.md
react_plan_q2_migration.md
Task Doc
docs/tasks/
task
{repo}_task_{name}.md
react_task_deps_update.md
模式：
${REPO}_${TYPE_CODE}_${SLUG}.md
文档类型文件夹类型码命名模式示例
组件文档
docs/components/
comp
{repo}_comp_{name}.md
react_comp_auth.md
变更日志
docs/changelogs/
cl
{repo}_cl_{YYYY-MM-DD}.md
react_cl_2026-02-28.md
ADR
docs/adrs/
adr
{repo}_adr_{NNN}_{slug}.md
react_adr_001_oauth.md
运行手册
docs/runbooks/
rb
{repo}_rb_{operation}.md
react_rb_deploy.md
用户指南
docs/guides/
guide
{repo}_guide_{topic}.md
react_guide_oauth_setup.md
技术文档
docs/technical/
tech
{repo}_tech_{topic}.md
react_tech_state_mgmt.md
Bug报告
docs/bugs/
bug
{repo}_bug_{issue}.md
react_bug_auth_timeout.md
计划
docs/plans/
plan
{repo}_plan_{initiative}.md
react_plan_q2_migration.md
任务文档
docs/tasks/
task
{repo}_task_{name}.md
react_task_deps_update.md

Index File

索引文件

After generating or updating docs, update 
docs/index.md
with links to all docs:
markdown
undefined
生成或更新文档后，需更新
docs/index.md
并添加所有文档的链接：
markdown
undefined

Documentation Index — react

Documentation Index — react

Last updated: 2026-02-28
Last updated: 2026-02-28

Component Docs

Component Docs

  • [[react_comp_auth]] — Authentication service
  • [[react_comp_auth]] — Authentication service

Changelogs

Changelogs

  • [[react_cl_2026-02-28]] — Feature release
  • [[react_cl_2026-02-28]] — Feature release

Guides

Guides

  • [[react_guide_oauth_setup]] — OAuth setup guide
  • [[react_guide_oauth_setup]] — OAuth setup guide

Technical

Technical

  • [[react_tech_state_mgmt]] — State management deep-dive

---
  • [[react_tech_state_mgmt]] — State management deep-dive

---

Workflow

工作流

1. Gather context     → Determine diff scope, identify repo
2. Extract diff data  → Run extraction scripts
3. Classify changes   → Identify what matters (see references/analysis-patterns.md)
4. Select templates  → Pick doc types (see references/templates.md)
5. Generate docs     → Write markdown with naming convention
6. Verify output     → Cross-check generated docs against diff
7. Present summary   → Show what was generated and why
8. Merge to central → After PR approval, merge to docs-microservices
1. 收集上下文     → 确定diff范围，识别仓库
2. 提取diff数据  → 执行提取脚本
3. 变更分类   → 识别核心改动（参考references/analysis-patterns.md）
4. 选择模板  → 匹配文档类型（参考references/templates.md）
5. 生成文档     → 遵循命名规范编写markdown
6. 输出校验     → 将生成文档与diff交叉核对
7. 展示摘要   → 说明生成的内容及原因
8. 合并到集中仓库 → PR获批后，合并到docs-microservices

Step 1: Gather Context

步骤1：收集上下文

Determine from the user's message (ask only if not inferrable):
  • Diff scope: Branch comparison (e.g., 
    feature/X
    vs 
    Develop
    ) or last N commits?
  • Repository: Which microservice is being documented?
  • Existing docs: Any docs to update rather than create from scratch?
从用户消息中提取以下信息（无法推断时再询问用户）：
  • Diff范围：分支对比（如
    feature/X
    与
    Develop
    对比）还是最近N次提交？
  • 仓库：需要生成哪个微服务的文档？
  • 已有文档：是否需要更新现有文档而非从零创建？

Ambiguity Protocol

歧义处理规则

If scope, branch, or repository is ambiguous, ask a focused question before generating docs.
  • Prefer an interactive question tool when available (single-select or multi-select options)
  • Ask one targeted question at a time, with a recommended default
  • Continue with safe defaults only when ambiguity does not change the output materially
Suggested question patterns:
  • Scope ambiguity: "Do you want documentation for current branch diff, a branch comparison, or last N commits?"
  • Repo ambiguity: "Which microservice should I document: react, integrator, magento, or all?"
Defaults (when not specified):
  • Diff scope: Current branch vs default branch (auto-detected from repo)
  • Repository: Auto-detect using 
    scripts/get-repo-name.sh
  • Output path: 
    ${GIT_REPO_ROOT}/docs/
    (local development phase)
  • Existing docs: Search 
    ${GIT_REPO_ROOT}/docs/
    for matching filenames before creating new docs
如果范围、分支或仓库信息不明确，生成文档前先提出针对性问题：
  • 优先使用交互式提问工具（单选或多选选项）
  • 每次仅提一个针对性问题，附带推荐默认值
  • 仅当歧义不会实质性改变输出内容时，才使用安全默认值继续执行
推荐提问模式：
  • 范围歧义："Do you want documentation for current branch diff, a branch comparison, or last N commits?"
  • 仓库歧义："Which microservice should I document: react, integrator, magento, or all?"
默认值（未指定时）：
  • Diff范围：当前分支与默认分支对比（从仓库自动识别）
  • 仓库：使用
    scripts/get-repo-name.sh
    自动检测
  • 输出路径：
    ${GIT_REPO_ROOT}/docs/
    （本地开发阶段）
  • 已有文档：创建新文档前先搜索
    ${GIT_REPO_ROOT}/docs/
    是否有匹配文件名

Repository Detection Guard (mandatory)

仓库检测规则（强制）

Run 
git status
before selecting a repo path.
  • If 
    git status
    succeeds: continue in current git repository
  • If 
    git status
    returns 
    fatal: not a git repository (or any of the parent directories): .git
    :
    • Treat current location as microservices root
    • Ask: "Which microservice(s) should I document: react, integrator, magento, or all?"
    • Accept answers like 
      react
      , 
      integrator
      , 
      magento
      , 
      todos
      /
      all
      , or comma-separated combinations
    • Resolve 
      all
      to all available microservice repos requested by user context
For each selected microservice, set 
REPO_PATH=<workspace-root>/<microservice>
and process independently.
选择仓库路径前先执行
git status
：
  • 如果
    git status
    执行成功：在当前git仓库继续操作
  • 如果
    git status
    返回
    fatal: not a git repository (or any of the parent directories): .git
    ：
    • 将当前位置视为微服务根目录
    • 询问用户："Which microservice(s) should I document: react, integrator, magento, or all?"
    • 可接受的回答包括
      react
      、
      integrator
      、
      magento
      、
      todos
      /
      all
      ，或逗号分隔的组合
    • 若用户选择
      all
      ，则覆盖用户上下文中提到的所有可用微服务仓库
对每个选中的微服务，设置
REPO_PATH=<workspace-root>/<microservice>
并独立处理。

Step 2: Extract Diff Data

步骤2：提取Diff数据

Use the extraction scripts from this skill's directory:
bash
undefined
使用本技能目录下的提取脚本：
bash
undefined

Get repository name (use this first!)

获取仓库名称（优先执行！）

REPO_NAME=$(bash <skill-path>/scripts/get-repo-name.sh <repo-path>)
REPO_NAME=$(bash <skill-path>/scripts/get-repo-name.sh <repo-path>)

Branch comparison with repo detection (recommended)

带仓库检测的分支对比（推荐）

bash <skill-path>/scripts/extract-diff-repo.sh <repo-path> --branch <target>
bash <skill-path>/scripts/extract-diff-repo.sh <repo-path> --branch <target>

Last N commits

最近N次提交

bash <skill-path>/scripts/extract-diff-repo.sh <repo-path> --commits 20
bash <skill-path>/scripts/extract-diff-repo.sh <repo-path> --commits 20

Filtered by path (for monorepos)

按路径过滤（适用于单体仓库）

bash <skill-path>/scripts/extract-diff-repo.sh <repo-path> --branch Develop --path services/auth/
bash <skill-path>/scripts/extract-diff-repo.sh <repo-path> --branch Develop --path services/auth/

Large diffs: start with --stat only

大Diff：仅先获取--stat统计信息

bash <skill-path>/scripts/extract-diff-repo.sh <repo-path> --branch feature/X --stat

For multi-repo workspaces, run per repository.
bash <skill-path>/scripts/extract-diff-repo.sh <repo-path> --branch feature/X --stat

多仓库工作空间下，每个仓库单独执行。

Per-Microservice Execution Rules (mandatory)

单微服务执行规则（强制）

For every selected microservice repository:
  1. Validate repo: 
    git -C <repo-path> rev-parse --is-inside-work-tree
  2. Write docs only inside that repo: 
    <repo-path>/docs/
  3. Never create docs outside a git repo
  4. Never create shared docs in workspace root
  5. Update 
    <repo-path>/docs/index.md
    for that repo
If multiple microservices are selected, repeat the full workflow per repo and present a grouped summary by microservice.
对每个选中的微服务仓库：
  1. 校验仓库有效性：
    git -C <repo-path> rev-parse --is-inside-work-tree
  2. 仅在对应仓库内写入文档：
    <repo-path>/docs/
  3. 禁止在git仓库外创建文档
  4. 禁止在工作空间根目录创建共享文档
  5. 更新对应仓库的
    <repo-path>/docs/index.md
如果选中多个微服务，每个仓库重复完整工作流，最终按微服务分组展示汇总结果。

Determine Document Category

确定文档分类

After extracting the diff, determine the target category for docs-microservices:
bash
CATEGORY=$(bash <skill-path>/scripts/get-doc-category.sh <change-type>)
提取diff后，确定文档在docs-microservices中的目标分类：
bash
CATEGORY=$(bash <skill-path>/scripts/get-doc-category.sh <change-type>)

Options: reference, engineering, reports, strategy

可选值: reference, engineering, reports, strategy

undefined
undefined

Large Diff Strategy

大Diff处理策略

When the diff is large (100+ files changed or output exceeds ~50KB):
  1. Start with 
    --stat
    only     — Use the file list and change counts to plan
  2. Read full diff only for high-impact files — APIs, schemas, configs, contracts, new files
  3. Read only changed hunks for medium-impact files — Business logic, services
  4. Skip full diff for low-impact files — Tests, formatting, comments
  5. Split by directory — If still too large, analyze one component/service at a time
当Diff过大（修改文件超过100个或输出超过~50KB）时：
  1. 仅先执行
    --stat
     — 基于文件列表和变更计数制定计划
  2. 仅读取高影响文件的完整Diff — API、schema、配置、契约、新增文件
  3. 仅读取中等影响文件的变更块 — 业务逻辑、服务
  4. 跳过低影响文件的完整Diff — 测试、格式调整、注释
  5. 按目录拆分 — 如果仍然过大，每次分析一个组件/服务

Step 3: Classify Changes

步骤3：变更分类

Read 
references/analysis-patterns.md
for the full classification guide.
Priority: High-impact changes (new components, public API changes, business logic changes, schema migrations, new dependencies, infra changes) are always documented. Medium-impact (internal refactors, test changes) only if significant. Low-impact (formatting, comments, patch bumps) are skipped.
Key distinctions (from analysis-patterns.md):
  • Business logic vs refactor: Did test expectations change? → business logic. Same tests pass? → refactor.
  • Interface exposure: External (public API) > Inter-component (shared packages) > Internal (same module). Document proportionally.
Map each significant change to doc types:
Change TypeImpactDoc Types
New component / moduleHighComponent Doc (new)
Public API changeHighComponent Doc + Changelog (Breaking if contract changed)
Business logic changeHighComponent Doc + Changelog
Inter-component interface changeHighComponent Doc + flag downstream consumers
Schema / data model changeHighADR + Component Doc
Major dependency addedMedium-HighADR + Component Doc
Infrastructure / deployment changeMediumRunbook
Internal refactor (same behavior)LowChangelog (Internal) or skip
Release milestone—Changelog
完整分类规则参考
references/analysis-patterns.md
。
优先级：高影响变更（新增组件、公共API变更、业务逻辑变更、schema迁移、新增依赖、基础设施变更）必须记录。中等影响变更（内部重构、测试变更）仅当改动较大时记录。低影响变更（格式调整、注释、补丁版本升级）可跳过。
核心区分规则（来自analysis-patterns.md）：
  • 业务逻辑 vs 重构：测试预期是否变更？→ 是则为业务逻辑变更，测试全部通过无改动则为重构。
  • 接口暴露优先级：外部（公共API）> 组件间（共享包）> 内部（同模块），按优先级对应文档详细程度。
将每个重要变更映射到对应文档类型：
变更类型影响程度文档类型
新增组件/模块高新增组件文档
公共API变更高组件文档 + 变更日志（如果契约变更标记为破坏性变更）
业务逻辑变更高组件文档 + 变更日志
组件间接口变更高组件文档 + 标记下游依赖方
Schema/数据模型变更高ADR + 组件文档
新增核心依赖中高ADR + 组件文档
基础设施/部署变更中运行手册
内部重构（行为无变化）低内部变更日志或跳过
发布里程碑—变更日志

Step 4: Select and Fill Templates

步骤4：选择并填充模板

Read 
references/templates.md
for all templates and the frontmatter schema.
Frontmatter rules:
  • ALWAYS include all required fields: 
    aliases
    , 
    type
    , 
    layer
    , 
    status
    , 
    owner
    , 
    tech_stack
    , 
    last_updated
    , 
    source_branch
    , 
    commit_range
  • Use 
    [[wiki-links]]
    for owner, tech_stack, and cross-references
  • Set 
    last_updated
    to today's date
  • Set 
    source_branch
    and 
    commit_range
    from the actual diff
  • Set 
    status
    honestly: 
    active
    , 
    debt
    , 
    zombie
    , or 
    gap
  • Populate 
    aliases
    with English keywords + Spanish equivalents
  • Infer 
    owner
    and 
    tech_stack
    using the heuristics in templates.md → "Inferring Frontmatter from Diffs"
  • Omit template sections that don't apply (e.g., don't include "Events Published" for a REST-only service)
所有模板和元数据头规范参考
references/templates.md
。
元数据头规则：
  • 必须包含所有必填字段：
    aliases
    、
    type
    、
    layer
    、
    status
    、
    owner
    、
    tech_stack
    、
    last_updated
    、
    source_branch
    、
    commit_range
  • 负责人、技术栈和交叉引用使用
    [[wiki-links]]
    格式
  • last_updated
    设置为当前日期
  • source_branch
    和
    commit_range
    使用实际diff的对应值
  • status
    如实设置：
    active
    （活跃）、
    debt
    （技术债务）、
    zombie
    （失效）、
    gap
    （缺失）
  • aliases
    字段填充英文关键词+西班牙语对应翻译
  • 参考templates.md中的启发式规则推断
    owner
    和
    tech_stack
    → 「从Diff推断元数据」
  • 省略不适用的模板章节（例如仅提供REST服务的文档不需要包含「发布事件」章节）

Step 5: Generate Docs

步骤5：生成文档

Write docs to the folder structure defined above.
Updating existing docs: Read first, preserve frontmatter structure, update 
last_updated
and 
commit_range
, modify only affected sections, append to "Recent Changes".
将文档写入上述定义的文件夹结构中。
更新现有文档：先读取原有内容，保留元数据头结构，更新
last_updated
和
commit_range
，仅修改受影响的章节，追加到「最近变更」部分。

Merge Strategy for Incremental Updates

增量更新合并策略

When a doc already exists:
SectionStrategy
FrontmatterMerge: Update 
last_updated
, 
commit_range
, 
status
. Preserve 
owner
, 
aliases
(append new ones)
What It DoesReplace only if the component's purpose fundamentally changed
API Surface / Exported APIMerge: Add new entries, update changed entries, mark removed entries as deprecated
DependenciesReplace with current state
ConfigurationMerge: Add new env vars, update changed ones
Key FilesReplace with current state
Recent ChangesAppend new changes at the top, keep last 5-10 entries
文档已存在时使用如下策略：
章节处理策略
元数据头合并：更新
last_updated
、
commit_range
、
status
，保留
owner
、
aliases
（追加新值）
功能说明仅当组件用途发生根本性变更时才替换
API暴露/导出API合并：新增条目，更新变更条目，将移除条目标记为已弃用
依赖替换为当前状态
配置合并：新增环境变量，更新变更的环境变量
核心文件替换为当前状态
最近变更在顶部追加新变更，保留最近5-10条记录

Step 6: Verify Output

步骤6：输出校验

Before presenting to the user, cross-check:
  • Every endpoint/export mentioned in docs exists in the diff or codebase
  • All frontmatter required fields are populated (no empty or placeholder values except 
    owner: "[[TBD]]"
    )
  • File paths referenced in "Key Files" actually exist
  • Breaking changes flagged in Changelog match actual contract changes in the diff
  • No duplicate docs (check existing files before creating new ones)
展示给用户前，交叉核对以下内容：
  • 文档中提到的每个端点/导出都真实存在于diff或代码库中
  • 所有必填元数据字段都已填充（除
    owner: "[[TBD]]"
    外无空值或占位符）
  • 「核心文件」中提到的文件路径真实存在
  • 变更日志中标记的破坏性变更与diff中的实际契约变更一致
  • 无重复文档（创建新文档前检查已有文件）

Step 7: Present Summary

步骤7：展示摘要

Show the user what was generated:
undefined
向用户展示生成的内容：
undefined

Documentation Generated

Documentation Generated

FileTypeReason
docs/components/react_comp_auth.mdComponent DocNew endpoints in routes/users.ts
docs/changelogs/react_cl_2026-02-28.mdChangelog12 commits with 3 features, 2 fixes
docs/guides/react_guide_oauth_setup.mdGuideOAuth integration guide
FileTypeReason
docs/components/react_comp_auth.mdComponent DocNew endpoints in routes/users.ts
docs/changelogs/react_cl_2026-02-28.mdChangelog12 commits with 3 features, 2 fixes
docs/guides/react_guide_oauth_setup.mdGuideOAuth integration guide

Key Changes Documented

Key Changes Documented

  • [bullets]
  • [条目列表]

Skipped (Low Impact)

Skipped (Low Impact)

  • [what and why]

Always update `${GIT_REPO_ROOT}/docs/index.md` with links to all generated docs (for multi-repo workspaces, do this per repository).
  • [跳过内容及原因]

始终更新`${GIT_REPO_ROOT}/docs/index.md`并添加所有生成文档的链接（多仓库工作空间下每个仓库单独更新）。

Step 8: Merge to docs-microservices (Post-PR)

步骤8：合并到docs-microservices（PR后）

After PR approval, merge the documentation to the centralized 
docs-microservices/
repository:
  1. Copy docs from each microservice 
    docs/
    folder to the corresponding category in 
    docs-microservices/
    :
    • docs/components/
      → 
      docs-microservices/reference/{repo}/
    • docs/changelogs/
      → 
      docs-microservices/reports/changelogs/
    • docs/adrs/
      → 
      docs-microservices/engineering/adrs/
    • docs/runbooks/
      → 
      docs-microservices/engineering/runbooks/
    • docs/guides/
      → 
      docs-microservices/reference/{repo}/
    • docs/technical/
      → 
      docs-microservices/reference/{repo}/
    • docs/bugs/
      → 
      docs-microservices/reports/bugs/
    • docs/plans/
      → 
      docs-microservices/strategy/plans/
  2. Update central index at 
    docs-microservices/index.md
  3. Cross-reference — Add links between services if applicable
bash
undefined
PR获批后，将文档合并到集中化的
docs-microservices/
仓库：
  1. 复制文档：将每个微服务
    docs/
    文件夹下的内容复制到
    docs-microservices/
    的对应分类：
    • docs/components/
      → 
      docs-microservices/reference/{repo}/
    • docs/changelogs/
      → 
      docs-microservices/reports/changelogs/
    • docs/adrs/
      → 
      docs-microservices/engineering/adrs/
    • docs/runbooks/
      → 
      docs-microservices/engineering/runbooks/
    • docs/guides/
      → 
      docs-microservices/reference/{repo}/
    • docs/technical/
      → 
      docs-microservices/reference/{repo}/
    • docs/bugs/
      → 
      docs-microservices/reports/bugs/
    • docs/plans/
      → 
      docs-microservices/strategy/plans/
  2. 更新集中索引：更新
    docs-microservices/index.md
  3. 交叉引用：如果适用，添加服务之间的链接
bash
undefined

Example workflow after PR approval

PR获批后示例工作流

Copy all docs from react to docs-microservices

将react的所有文档复制到docs-microservices

cp -r react/docs/components/* docs-microservices/reference/react/ cp -r react/docs/changelogs/* docs-microservices/reports/changelogs/ cp -r react/docs/adrs/* docs-microservices/engineering/adrs/ cp -r react/docs/runbooks/* docs-microservices/engineering/runbooks/ cp -r react/docs/guides/* docs-microservices/reference/react/ cp -r react/docs/technical/* docs-microservices/reference/react/ cp -r react/docs/bugs/* docs-microservices/reports/bugs/ cp -r react/docs/plans/* docs-microservices/strategy/plans/

**Merge criteria**:
- PR must be approved and merged
- Docs must follow naming convention
- All frontmatter fields must be complete

---
cp -r react/docs/components/* docs-microservices/reference/react/ cp -r react/docs/changelogs/* docs-microservices/reports/changelogs/ cp -r react/docs/adrs/* docs-microservices/engineering/adrs/ cp -r react/docs/runbooks/* docs-microservices/engineering/runbooks/ cp -r react/docs/guides/* docs-microservices/reference/react/ cp -r react/docs/technical/* docs-microservices/reference/react/ cp -r react/docs/bugs/* docs-microservices/reports/bugs/ cp -r react/docs/plans/* docs-microservices/strategy/plans/

**合并标准**：
- PR必须已获批且合并
- 文档必须遵循命名规范
- 所有元数据字段必须完整

---

Quality Rules

质量规则

  • No fluff: Every sentence carries information. Cut filler.
  • Trace to code: Every claim references a file, commit, or config.
  • Tables over prose: For endpoints, env vars, dependencies — always tables.
  • Be honest: If the diff reveals tech debt, set 
    status: debt
    . Living docs tell the truth.
  • Aliases matter: Include concept name, Spanish translation, common abbreviations.
  • Omit empty sections: Don't include template sections that have no content for this component.
  • 无冗余内容：每句话都承载有效信息，删除无用填充内容
  • 可追溯到代码：每个结论都关联对应文件、提交或配置
  • 优先使用表格：端点、环境变量、依赖等内容优先用表格展示
  • 如实记录：如果diff中发现技术债务，设置
    status: debt
    ，活文档需要反映真实情况
  • 别名不可少：包含概念名称、西班牙语翻译、常用缩写
  • 省略空章节：不包含当前组件无内容的模板章节

Few-Shot Example

小样本示例

Input: Diff Summary

输入：Diff摘要

=== REPO: react ===
=== BRANCH: feature/oauth vs Develop ===
=== COMMIT RANGE: a1b2c3d..d4e5f6g ===

=== FILE STATS ===
 src/routes/auth.ts   | 45 +++++++++--
 src/services/oauth.ts | 120 ++++++++++++++++++++++++++++
 src/types/auth.dto.ts |  15 ++++
 package.json          |   2 +  (added passport-google-oauth20)
 tests/oauth.test.ts   |  85 ++++++++++++++++++++

=== COMMIT LOG ===
a1b2c3d feat: add Google OAuth2 login flow
d4e5f6g feat: add OAuth callback handler
h7i8j9k fix: handle missing email in OAuth profile
l0m1n2o chore: add passport-google-oauth20 dependency
=== REPO: react ===
=== BRANCH: feature/oauth vs Develop ===
=== COMMIT RANGE: a1b2c3d..d4e5f6g ===

=== FILE STATS ===
 src/routes/auth.ts   | 45 +++++++++--
 src/services/oauth.ts | 120 ++++++++++++++++++++++++++++
 src/types/auth.dto.ts |  15 ++++
 package.json          |   2 +  (added passport-google-oauth20)
 tests/oauth.test.ts   |  85 ++++++++++++++++++++

=== COMMIT LOG ===
a1b2c3d feat: add Google OAuth2 login flow
d4e5f6g feat: add OAuth callback handler
h7i8j9k fix: handle missing email in OAuth profile
l0m1n2o chore: add passport-google-oauth20 dependency

Output: Classification

输出：分类结果

  1. New OAuth service file (oauth.ts, 120 lines) → High impact, new feature → Component Doc
  2. Route changes (auth.ts, 45 lines) → Public API change → Component Doc + Changelog
  3. New major dependency (passport-google-oauth20) → Technical Guide (integration)
  4. New tests with different expectations → Confirms business logic change
  1. 新增OAuth服务文件（oauth.ts，120行）→ 高影响，新功能 → 组件文档
  2. 路由变更（auth.ts，45行）→ 公共API变更 → 组件文档 + 变更日志
  3. 新增核心依赖（passport-google-oauth20）→ 技术指南（集成）
  4. 新增测试且预期变更 → 确认属于业务逻辑变更

Output: Generated Docs

输出：生成文档

Using folder structure + naming convention 
${REPO}_${TYPE}_${SLUG}.md
:
  • docs/components/react_comp_auth.md
    — Updated: added OAuth endpoints, new key files
  • docs/changelogs/react_cl_2026-02-28.md
    — New: 2 features (OAuth login, callback handler), 1 fix
  • docs/guides/react_guide_oauth_google.md
    — New: Guide for Google OAuth integration
  • docs/technical/react_tech_oauth_architecture.md
    — New: Technical deep-dive on OAuth flow
遵循文件夹结构+命名规范
${REPO}_${TYPE}_${SLUG}.md
：
  • docs/components/react_comp_auth.md
    — 已更新：添加OAuth端点、新增核心文件
  • docs/changelogs/react_cl_2026-02-28.md
    — 新增：2个功能（OAuth登录、回调处理）、1个修复
  • docs/guides/react_guide_oauth_google.md
    — 新增：Google OAuth集成指南
  • docs/technical/react_tech_oauth_architecture.md
    — 新增：OAuth流程技术深度解析

Resources

资源

  • scripts/extract-diff.sh
    — Extract structured diff data (file stats, commit log, full diff)
  • scripts/extract-diff-repo.sh
    — Extract diff with automatic repository name detection
  • scripts/get-repo-name.sh
    — Get the current git repository name
  • scripts/get-doc-category.sh
    — Determine destination category (reference/engineering/reports/strategy)
  • references/templates.md
    — All doc templates with frontmatter schema
  • references/analysis-patterns.md
    — How to classify changes from diffs
  • scripts/extract-diff.sh
    — 提取结构化diff数据（文件统计、提交日志、完整diff）
  • scripts/extract-diff-repo.sh
    — 自动识别仓库名称提取diff
  • scripts/get-repo-name.sh
    — 获取当前git仓库名称
  • scripts/get-doc-category.sh
    — 确定目标分类（reference/engineering/reports/strategy）
  • references/templates.md
    — 所有文档模板及元数据头规范
  • references/analysis-patterns.md
    — 如何从diff分类变更