datai/datai-scenes/datai-scene-salesforce/docs/skill/0002-establish-ssot-hub.md

name	description
0002-establish-ssot-hub	建立项目唯一真源中心，创建 docs/index.md 作为项目文档的唯一入口

技能：建立真源中心 (Establish SSOT Hub)

元数据 (Metadata)

• name: establish-ssot-hub
• description: 建立项目唯一真源中心，创建 docs/index.md 作为项目文档的唯一入口
• version: 1.0.0
• author: SSOT Architect
• lastUpdated: 2026-01-15

触发与定位 (Triggers & Scope)

触发条件 (Triggers)

当以下情况发生时，AI 应当"觉醒"本技能：

1. Bootstrap 完成: 完成项目协作基线初始化后
2. 缺少文档入口: 检测到 docs/index.md 不存在
3. 文档索引更新: 创建新的需求、设计、决策或提示词文档后
4. 孤儿文件检测: 发现未被索引的文档文件
5. 工作流阶段 2: 用户进入工作流的"建立真源中心"阶段

定位范围 (Scope)

• 适用模块: 所有 Datai 项目模块
• 影响文件: docs/index.md
• 索引范围: docs/ 下的所有子目录和文档
• 相关技能: skill-bootstrap-workflow, skill-setup-information-architecture

核心指令集 (Instructions)

架构约束 (Architecture Constraints)

1. docs/index.md 的核心规则:

   • 这是项目的唯一文档入口
   • 它不仅是列表，更是导航图
   • 必须包含对 Requirements, Design, ADRs, Prompts, Sessions, Retros 的动态索引
   • 严禁出现"孤儿文件"（即未被 index 索引的文件）

2. 必须索引的文档类型:

   • docs/requirements/ - 需求文档
   • docs/design/ - 系统设计文档
   • docs/decisions/adr/ - 架构决策记录
   • docs/prompts/ - 提示词资产
   • docs/sessions/ - AI 会话快照
   • docs/retros/ - 迭代复盘
   • docs/changelog/ - 变更记录
   • docs/skills/ - 技能文档

3. 索引结构要求:

   • 按文档类型分组
   • 每个文档必须包含状态标识（Draft/In Progress/Completed）
   • 必须包含文档的创建/更新日期
   • 必须包含文档的简要描述

业务逻辑 SOP (Business Logic SOP)

步骤 1: 检查 docs/index.md 是否存在

# 检查文档入口是否存在
if [ ! -f "docs/index.md" ]; then
    echo "警告: docs/index.md 不存在，需要创建"
fi

步骤 2: 扫描 docs/ 目录结构

# 使用 LS 工具扫描 docs/ 目录
# 列出所有子目录和文件

步骤 3: 识别孤儿文件

# 读取 docs/index.md 内容
# 提取所有已索引的文档路径
# 对比 docs/ 目录中的实际文件
# 标记未被索引的文件为"孤儿文件"

步骤 4: 创建或更新 docs/index.md

# Datai 项目文档中心 (SSOT Hub)

> 本文档是项目的唯一真源入口，所有文档必须在此索引。

## 📋 文档导航

### 📝 需求文档 (Requirements)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [REQ-001](requirements/REQ-001.md) | ✅ Completed | 初始需求 | 2026-01-15 |
| [REQ-002](requirements/REQ-002.md) | 🔄 In Progress | 新功能需求 | 2026-01-15 |

### 🏗️ 系统设计 (Design)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [DES-001](design/DES-001.md) | ✅ Completed | 架构设计 | 2026-01-15 |
| [DES-002](design/DES-002.md) | 📝 Draft | 接口设计 | 2026-01-15 |

### 🎯 架构决策 (ADRs)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [ADR-001](decisions/adr/ADR-001.md) | ✅ Accepted | 技术栈选择 | 2026-01-15 |
| [ADR-002](decisions/adr/ADR-002.md) | 📝 Draft | 数据库设计 | 2026-01-15 |

### 💡 提示词资产 (Prompts)
| 文档 | 版本 | 描述 | 更新日期 |
|------|------|------|----------|
| [PROMPT-001](prompts/PROMPT-001.md) | v1.0.0 | 工作流提示词 | 2026-01-15 |
| [PROMPT-002](prompts/PROMPT-002.md) | v1.0.0 | 代码生成提示词 | 2026-01-15 |

### 🗣️ 会话记录 (Sessions)
| 文档 | 触发 | 结果 | 日期 |
|------|------|------|------|
| [20260115-TaskName](sessions/20260115-TaskName.md) | REQ-001 | Commit: abc123 | 2026-01-15 |

### 🔄 迭代复盘 (Retros)
| 文档 | 类型 | 日期 |
|------|------|------|
| [20260115-Review](retros/20260115-Review.md) | Sprint Review | 2026-01-15 |

### 📊 变更记录 (Changelog)
| 文档 | 版本 | 日期 |
|------|------|------|
| [CHANGELOG](changelog/CHANGELOG.md) | v1.0.0 | 2026-01-15 |

### 🛠️ 技能文档 (Skills)
| 文档 | 描述 | 版本 |
|------|------|------|
| [Bootstrap Workflow](skills/0001-bootstrap-workflow.md) | 项目协作基线初始化 | v1.0.0 |
| [SSOT Hub](skills/0002-establish-ssot-hub.md) | 建立真源中心 | v1.0.0 |

## ⚠️ 孤儿文件警告

以下文档未被索引，请及时处理：
- [文件路径](file/path) - 原因说明

## 📊 统计信息

- 需求文档: X 个
- 设计文档: X 个
- 架构决策: X 个
- 提示词资产: X 个
- 会话记录: X 个
- 迭代复盘: X 个
- 变更记录: X 个
- 技能文档: X 个

## 🔗 快速链接

- [项目 README](../README.md)
- [贡献指南](../CONTRIBUTING.md)
- [变更日志](../CHANGELOG.md)

步骤 5: 验证索引完整性

# 验证所有文档都被索引
# 检查是否有孤儿文件
# 如果有，提示用户处理

工具调用 (Tool Usage)

1. 目录扫描工具:

   • 使用 LS 工具递归扫描 docs/ 目录
   • 列出所有文件和子目录

2. 文件读取工具:

   • 使用 Read 工具读取 docs/index.md 现有内容
   • 使用 Read 工具读取各文档的元数据

3. 文件搜索工具:

   • 使用 Grep 工具搜索文档中的元数据标记
   • 使用 SearchCodebase 工具查找特定类型的文档

4. 文件创建/更新工具:

   • 使用 Write 工具创建或更新 docs/index.md
   • 确保索引格式一致

错误陷阱与验证 (Anti-Patterns & Checklist)

常见错误 (Anti-Patterns)

1. 错误: 创建了新文档但未更新 docs/index.md

   • 后果: 产生孤儿文件，违反 SSOT 原则
   • 修正: 每次创建新文档后必须更新索引

2. 错误: docs/index.md 只是简单的文件列表

   • 后果: 无法作为有效的导航图
   • 修正: 必须包含状态、描述、日期等元数据

3. 错误: 索引格式不一致

   • 后果: 难以维护和查找
   • 修正: 使用统一的 Markdown 表格格式

4. 错误: 忽略孤儿文件警告

   • 后果: 文档结构混乱，违反 SSOT 原则
   • 修正: 及时处理或删除孤儿文件

5. 错误: 删除文档后未更新索引

   • 后果: 索引包含无效链接
   • 修正: 删除文档时同步更新索引

验收清单 (Acceptance Checklist)

• docs/index.md 已创建或更新
• 所有文档类型都已索引
• 每个文档都包含状态标识
• 每个文档都包含创建/更新日期
• 每个文档都包含简要描述
• 没有孤儿文件
• 索引格式统一
• 统计信息准确
• 快速链接有效

Correct vs Incorrect 对比

Correct 示例

### 📝 需求文档 (Requirements)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [REQ-001](requirements/REQ-001.md) | ✅ Completed | 初始需求 | 2026-01-15 |
| [REQ-002](requirements/REQ-002.md) | 🔄 In Progress | 新功能需求 | 2026-01-15 |

Incorrect 示例

### 需求文档
- REQ-001.md
- REQ-002.md

问题: 缺少状态、描述、日期等元数据，无法作为有效的导航图。

相关文档 (Related Documents)

• 工作流提示词
• Bootstrap 工作流技能
• 信息架构设置技能
• SSOT 原则