update-knowledge-base

COG ナレッジベース更新スキル

呼び出すタイミング

• リリース後 — 新機能や変更点を反映して、製品ナレッジを更新します
• ユーザーが「ナレッジベースを更新」「KBを更新」「ナレッジを同期」「製品ドキュメントを更新」と言ったとき
• 定期メンテナンス — ナレッジベースに現在の製品の状態が反映されていることを確認します
• 主要な機能のリリース、アーキテクチャの変更、または非推奨化の後

エージェントモードの確認

00-inbox/MY-PROFILE.md のフロントマターにある agent_mode を確認します：

• agent_mode: team の場合 — 複数のソースをスキャンし、複数のナレッジファイルを同時に更新するために、並列エージェントを使用します
• agent_mode: solo の場合 — 更新を順番に、一度に1つのナレッジファイルずつ処理します

コマンド：/update-knowledge-base

事前確認

1. **00-inbox/MY-INTEGRATIONS.md を読み、**有効なデータソースと公開先を確認します
2. **00-inbox/MY-PROFILE.md を読み、**有効なプロジェクトを確認します
3. 現在のタイムスタンプを取得します： Bash を使って date '+%Y-%m-%d %H:%M' を実行します
4. 既存のナレッジベースをスキャンします： 05-knowledge/**/*.md を Glob し、現在の状態を把握します

---

実行戦略

フェーズ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：更新データを収集する

チームモード（並列エージェント）

run_in_background: true を指定して Task ツールを使い、データ収集エージェントを起動します：

エージェント：「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

エージェント：「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

エージェント：「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

ソロモード

更新のきっかけに応じて、最も関連性の高いエージェントを順番に実行します。

フェーズ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. フロントマターの last_updated を更新します
5. version を更新します（マイナーバージョンを増やします）

4.3 非推奨化を記録する

非推奨になったエントリーについて：

1. フロントマターに 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

---

フォールバック時の動作

状況	動作
有効なトラッカーがない	Vault 内のデータのみを使用します（リリースノート、PRD、プロジェクトファイル）
既存の KB エントリーがない	最初のナレッジベース構成と初回エントリーを作成します
Wiki 同期に失敗した	変更はすべてローカルに保存済みです。手動で同期するようユーザーに伝えます
KB の規模が非常に大きい（50 ファイル超）	バッチに分けて処理し、最近変更されたエントリーを優先します
最近の変更が見つからない	KB が最新であることを報告し、定期レビューのトピックを提案します
情報が矛盾している	自動で解決せず、ユーザーが解決できるよう矛盾点を示します

エラー処理

• ファイルの競合：更新内容が最近の手動編集と矛盾する場合は、両方のバージョンをユーザーに提示します
• コンテキストの超過：ナレッジファイルを10件ずつ処理します
• 古いデータソース：トラッカーのデータが古いと思われる場合は、警告します（API の問題）
• プロジェクトコンテキストの不足：ナレッジがどのプロジェクトに関するものか、ユーザーに確認します