# SSoT 監査ガイド

スキル作成・更新時に必ず実行する SSoT（Single Source of Truth）監査の手順。**この監査を通過するまでスキルを完成扱いにしない。**

## 目次

- SSoT 違反とは
- 違反パターンと修正方法
- 監査手順
- 判断に迷うケース
- ハードコード・不整合レビュー

---

## SSoT 違反とは

**同じ情報が2箇所以上に存在し、片方を更新しても他方が古いまま残るリスクがある状態。**

スキルにおける SSoT 違反は2つの場面で発生する:

1. **スキル内部**: SKILL.md と references/ の間で情報が重複
2. **スキル ↔ 外部**: スキルが参照するファイル（スキーマ、設定、コード）の情報をスキル内にコピー

---

## 違反パターンと修正方法

### パターン1: スキーマ・設定のコピー

```markdown
# 違反
## 出力形式
JSONは以下の構造:
- name: string (必須)
- age: number (任意)
- email: string (必須)

# 正解
## 出力形式
SSoT: `path/to/schema.ts` の型定義を参照
```

### パターン2: ルール一覧の転記

```markdown
# 違反
## バリデーション
以下のルールでチェック:
1. nameは3文字以上
2. emailは@を含む
3. ageは0以上

# 正解
## バリデーション
SSoT: `path/to/validator.ts` のバリデーションルールに従う
```

### パターン3: SKILL.md と references/ の重複

```markdown
# 違反
SKILL.md に品質チェックリストを書き、references/exemplar.md にも同じリストがある

# 正解
チェックリストは exemplar.md のみに記載。SKILL.md は「品質チェック → exemplar.md」と参照
```

### パターン4: 他スキルとの重複

```markdown
# 違反
スキルAとスキルBの両方に同じデプロイ手順を記載

# 正解
共通手順を共有リファレンスに置き、両方から参照
```

---

## 監査手順

スキルの作成・更新が完了したら、以下の全ステップを実行する。

### Step 1: 情報ソースの列挙

スキルが参照する外部ファイルを全て列挙する:

- スキーマファイル（.ts, .json）
- 設定ファイル
- 他のスキルの references/
- プロジェクトのドキュメント

### Step 2: スキル内コンテンツの監査

SKILL.md と references/ 内の**各テーブル・リスト・コードブロック**について問う:

**「この情報の真のソース（原本）はどこか？」**

- **スキル内が原本** → Step 3 へ
- **スキル外に原本がある** → 違反。参照に置き換える

### Step 3: 重複の検索

スキル内が原本の情報について、プロジェクト内に同じ情報がないか確認:

```bash
grep -r "キーワード" --include="*.md" --include="*.ts" --include="*.json"
```

重複が見つかったら:
- どちらを原本にするか決定
- もう片方を参照に置き換え

### Step 4: スキル内部の重複チェック

SKILL.md と references/ の間で同じ情報が書かれていないか確認:

- SKILL.md に書いた内容が references/ にもないか
- references/ の複数ファイルに同じ情報がないか

### Step 5: 最終確認

以下を全て満たすことを確認:

- [ ] スキル内の全テーブル・リストが「このスキルでしか定義されていない情報」のみを含む
- [ ] 外部ファイルの情報をスキル内にコピーしていない
- [ ] SKILL.md と references/ の間に重複がない
- [ ] references/ の複数ファイル間に重複がない

---

## 判断に迷うケース

### 「要約」は許されるか？

**原則: 方向性を示す一文は許容。詳細リストのコピーは禁止。**

```markdown
# OK: 方向性だけ示して参照
## 概要
核心原則に基づいてスキルを設計する。
詳細 → references/principles.md

# NG: リストのコピー（要約に見せかけた重複）
## 概要
原則:
- 洗練: 公式ドキュメントに基づく
- 簡潔性: 必要最小限の情報
- SSoT: 情報は1箇所のみ
```

判断基準: **「参照先が変更された時、この記述も更新が必要か？」**
- Yes → SSoT 違反。参照に置き換える
- No → 許容

### テーブルの一部引用は？

**禁止。** テーブルの一部でも、元テーブルに行が追加された時に古くなる。

```markdown
# NG: 一部引用
主要なイベント: afterFileEdit, stop（全一覧は references/ を参照）

# OK: 参照のみ
イベント一覧 → references/events.md
```

### 「例」としての引用は？

**形式の例示は1つだけ許容。内容の列挙は禁止。**

```markdown
# OK: 形式を1つだけ示す
フロントマターの例:
---
name: my-skill
description: ...
---
詳細な書き方 → exemplar.md

# NG: 複数パターンの列挙（内容のコピー）
良い例:
- feat(認証): メールアドレスでのログイン機能を追加
- fix(決済): 税率計算の誤りを修正
悪い例:
- バグを修正
- 対応
```

---

## ハードコード・不整合レビュー

SSoT 監査（上記 Step 1〜5）が「情報のコピー」を検出するのに対し、このレビューは **ハードコードされた詳細** と **暗黙的な依存** を検出する。SSoT 監査を通過したスキルに対して追加で実行する。

### チェック1: ハードコードされた詳細情報

参照先を読めばわかる**具体的な値・構造・手順**がスキル内に直接書かれていないか確認する。

**検出対象**:

- ディレクトリ構造の展開（ツリー表示）
- 設定値・パラメータの列挙
- 外部ツールのコマンドオプション一覧
- スキーマのフィールド名・型の網羅的リスト
- ファイルパスの詳細な列挙

**判断基準**: 「この詳細が変更されたとき、スキルを手動で更新する必要があるか？」

- Yes → 参照に置き換えるか、方向性のみの記述に変更
- No → 許容

```markdown
# NG: ディレクトリ構造をハードコード
## 出力先
contents/
├── 講義/
│   └── Nヶ月目/第N回/
│       ├── meta.json
│       ├── slides.json
│       └── script.md

# OK: 参照先を示す
## 出力先
`contents/講義/` 配下に、実際のディレクトリ構造に従って配置する。
```

### チェック2: 参照先変更時の不整合リスク

スキル内の記述が参照先の内容に**暗黙的に依存**していないか確認する。コピーではないが、参照先の更新により事実と乖離するリスクのある記述を検出する。

**検出対象**:

- 参照先の件数に依存する表現（「3つの原則」「5つのステップ」）
- 参照先の内容を要約した記述（要約は参照先が変われば古くなる）
- 参照先の特定ステップ名・ラベルをインラインで使った記述

**判断基準**: 「参照先のファイルが更新されたとき、この記述はまだ正確か？」

- 不確実 → 参照先に依存しない表現に書き換える
- 常に正確 → 許容

```markdown
# NG: 参照先の個数に暗黙的に依存
3つの核心原則に基づいてスキルを設計する。
→ 原則が追加・削除されたら不正確になる

# OK: 個数に依存しない
核心原則に基づいてスキルを設計する。
詳細 → references/principles.md
```

### レビュー最終確認

以下を全て満たすことを確認:

- [ ] スキル内にディレクトリ構造・スキーマ・設定値のベタ書きがない
- [ ] 参照先の件数・名前に依存する表現がない
- [ ] 参照先が更新されてもスキル内の記述が正確なままである