update-knowledge-base

COG 更新知识库技能

何时调用

• 发布后 — 用新功能和变更更新产品知识
• 用户说“更新知识库”“更新 KB”“同步知识”“更新产品文档”
• 定期维护 — 确保知识库反映产品当前状态
• 重大功能发布、架构变更或弃用后

Agent 模式识别

检查 00-inbox/MY-PROFILE.md frontmatter 中的 agent_mode：

• 如果 agent_mode: team — 使用并行 Agent 扫描多个来源，同时更新多个知识文件
• 如果 agent_mode: solo — 按顺序处理更新，每次处理一个知识文件

命令：/update-knowledge-base

执行前检查

1. 读取 00-inbox/MY-INTEGRATIONS.md，了解活跃数据源和发布目标
2. 读取 00-inbox/MY-PROFILE.md，了解活跃项目
3. 获取当前时间戳： 使用 Bash 运行 date '+%Y-%m-%d %H:%M'
4. 扫描现有知识库： 使用 Glob 检查 05-knowledge/**/*.md，了解当前状态

---

执行策略

阶段 1：确定更新范围

询问用户（或根据上下文推断）：

What triggered this knowledge base update?

a) New release shipped (I'll pull changes from release notes and tracker)
b) Feature launched or updated (I'll document the feature)
c) Architecture or technical change (I'll update technical knowledge)
d) Periodic review (I'll scan for anything that's changed since last update)
e) Custom — describe what needs updating

阶段 2：收集更新数据

Team 模式（并行 Agent）

使用 Task 工具启动数据收集 Agent，并设置 run_in_background: true：

Agent：“release-scanner”（用于由发布触发的更新）

Scan recent releases and release notes for knowledge base updates.

1. Check vault for recent release notes:
   Glob: 04-projects/*/release-notes/*.md
   Read the most recent release notes for each active project

2. If GitHub is active:
   gh release list --repo [CUSTOMIZE: your-org/your-repo] --limit 5 --json tagName,name,body,publishedAt
   Get the latest release details

3. If Linear is active:
   Use ToolSearch to load Linear tools
   Check recently completed cycles and milestones for shipped features

Extract from each source:
- New features added (name, description, user impact)
- Features modified (what changed)
- Features deprecated or removed
- Technical changes (architecture, API, infrastructure)
- Bug fixes that affect documented behavior

Return: structured list of knowledge updates needed

Agent：“existing-kb-auditor”

Audit the current knowledge base for staleness and gaps.

1. Read all files in 05-knowledge/:
   Glob: 05-knowledge/**/*.md

2. For each file, extract:
   - Last updated date (from frontmatter or file modification)
   - Topics covered
   - Products/features documented
   - Any [TODO] or [OUTDATED] markers

3. Cross-reference with active projects from MY-PROFILE.md:
   - Are all active projects represented in the KB?
   - Are there KB entries for discontinued/inactive projects?

4. Check for:
   - Files not updated in >90 days (potentially stale)
   - Topics mentioned in recent release notes but missing from KB
   - Contradictions between KB entries and recent changes

Return: staleness report, gap analysis, and recommended updates

Agent：“tracker-feature-collector”（用于由功能触发的更新）

Collect current feature/product state from project trackers.

If Linear is active:
1. Use ToolSearch to load Linear tools
2. List all projects and their current status: mcp__claude_ai_Linear_2__list_projects
3. List all initiatives: mcp__claude_ai_Linear_2__list_initiatives
4. For key initiatives, get details: mcp__claude_ai_Linear_2__get_initiative

If GitHub is active:
1. Check repo README and docs for current feature descriptions
2. Review recent PRs that touch documentation:
   gh pr list --repo [CUSTOMIZE: your-org/your-repo] --state merged --search "label:docs merged:>=[30_DAYS_AGO]" --json number,title,body --limit 20

Return: current product/feature state for knowledge base comparison

Solo 模式

根据更新触发原因，按顺序运行最相关的 Agent。

阶段 3：确定知识更新内容

将收集到的数据与现有知识库进行比较，确定：

1. 需要新增的条目 — 尚未记录的功能、产品或主题
2. 需要更新的内容 — 需要修改的现有条目
3. 弃用／移除 — 关于已不存在功能的条目
4. 补充缺失内容 — 缺少的上下文、示例或交叉引用

向用户展示更新计划：

Knowledge Base Update Plan:

NEW entries to create:
1. [Topic] — [reason: new feature in v[X]]
2. [Topic] — [reason: gap identified]

UPDATES to existing entries:
1. 05-knowledge/[file].md — [what needs changing]
2. 05-knowledge/[file].md — [what needs changing]

DEPRECATION candidates:
1. 05-knowledge/[file].md — [reason: feature removed in v[X]]

STALE entries (>90 days, may need review):
1. 05-knowledge/[file].md — last updated [date]

Proceed with these updates? (yes / modify plan / skip specific items)

进行更改前，等待用户批准。

阶段 4：执行更新

4.1 创建新的知识条目

为每个新条目使用此模板：

---
type: knowledge
domain: [product/technical/process/architecture]
project: [project-name]
topic: [topic name]
created: [YYYY-MM-DD HH:MM]
last_updated: [YYYY-MM-DD]
source: [release-notes/feature-launch/manual/periodic-review]
version: "1.0"
tags: ["#knowledge", "#[project]", "#[topic-area]"]
related:
  - [path to related KB entry]
  - [path to related project file]
---

# [Topic Title]

## Overview
[Clear, concise description of the topic — what it is, why it matters]

## Current State
[How this feature/system/process works as of the last update]

### Key Details
- **[Detail 1]:** [Value/description]
- **[Detail 2]:** [Value/description]
- **[Detail 3]:** [Value/description]

## History
| Date | Version | Change | Source |
|------|---------|--------|--------|
| [Date] | [Version] | [What changed] | [Release notes / PR / manual] |

## Related
- [Link to related KB entries]
- [Link to PRDs if applicable]
- [Link to project files]

## Notes
[Additional context, caveats, or open questions]

---

*Last updated: [YYYY-MM-DD] | Source: [what triggered this update]*

保存到：05-knowledge/[domain]/[topic-slug].md

mkdir -p "05-knowledge/[domain]"

4.2 更新现有条目

对于每项更新：

1. 读取现有文件
2. 更新相关章节
3. 在 History 表中添加一行
4. 更新 frontmatter 中的 last_updated
5. 更新 version（递增次版本号）

4.3 标记弃用内容

对于已弃用的条目：

1. 在 frontmatter 中添加 status: deprecated
2. 在文件顶部添加弃用通知：

   > **DEPRECATED:** This feature was removed/replaced in [version/date]. See [replacement link] for the current approach.
   

3. 不要删除文件 — 历史背景很有价值

阶段 5：生成更新摘要

创建更新日志：

---
type: kb-update-log
date: [YYYY-MM-DD]
created: [YYYY-MM-DD HH:MM]
trigger: [release/feature/periodic/manual]
tags: ["#knowledge", "#update-log"]
---

# Knowledge Base Update — [YYYY-MM-DD]

## Trigger
[What caused this update: release X.Y.Z / feature launch / periodic review]

## Changes Made

### New Entries
| File | Topic | Domain | Source |
|------|-------|--------|--------|
| [path] | [topic] | [domain] | [source] |

### Updated Entries
| File | Changes | Previous Version | New Version |
|------|---------|-----------------|-------------|
| [path] | [summary of changes] | [old ver] | [new ver] |

### Deprecated Entries
| File | Reason | Replacement |
|------|--------|-------------|
| [path] | [reason] | [link to replacement or N/A] |

## Knowledge Base Health
- **Total entries:** [N]
- **Updated this session:** [N]
- **Created this session:** [N]
- **Deprecated this session:** [N]
- **Stale entries remaining (>90 days):** [N]
- **Coverage:** [assessment of how well the KB covers active projects]

---

*Generated by COG Knowledge Base Updater*

保存到：05-knowledge/_logs/kb-update-YYYY-MM-DD.md

mkdir -p "05-knowledge/_logs"

阶段 6：可选的 Wiki 同步（需要批准）

如果 Confluence 或 Notion 处于活跃状态，询问是否同步已更新的条目：

Knowledge base updated locally. Would you like to sync to your wiki?

Active wiki platforms:
- [Confluence / Notion — whichever is active]

Options:
a) Sync all changed entries to [platform]
b) Sync specific entries only
c) Skip wiki sync (vault-only)

绝不自动发布。必须等待明确批准。

Confluence 同步

对于要同步的每个条目，使用 /publish-to-confluence 技能模式。

Notion 同步

1. Use ToolSearch to load Notion tools
2. Search for existing pages matching the KB entry: mcp__claude_ai_Notion__notion-search
3. If exists: update with mcp__claude_ai_Notion__notion-update-page
4. If new: create with mcp__claude_ai_Notion__notion-create-pages

---

知识库组织结构

建议的 05-knowledge/ 结构：

05-knowledge/
  _logs/                    # Update logs
    kb-update-YYYY-MM-DD.md
  product/                  # Product features, capabilities, roadmap
    [feature-name].md
  technical/                # Architecture, APIs, infrastructure
    [system-name].md
  process/                  # Team processes, workflows, conventions
    [process-name].md
  domain/                   # Domain knowledge, industry context
    [topic-name].md
  integrations/             # Integration docs, API references
    [integration-name].md

---

备用处理方式

情况	处理方式
没有活跃的跟踪器	仅使用知识库数据（发布说明、PRD、项目文件）
没有现有知识库条目	创建初始知识库结构和首批条目
Wiki 同步失败	所有更改已保存在本地；告知用户手动同步
知识库规模很大（>50 个文件）	分批处理，优先处理最近更改的条目
未发现近期更改	报告知识库已是最新状态；建议定期回顾主题
信息冲突	标记冲突并交由用户处理，不要自动解决

错误处理

• 文件冲突：如果更新内容与近期的手动编辑相矛盾，请向用户展示两个版本
• 上下文溢出：每批处理 10 个知识文件
• 数据源过时：如果跟踪器数据似乎已过时（API 问题），请发出警告
• 项目上下文缺失：询问用户这些知识与哪个项目相关