voice-learn

音声学習スキル

ユーザーによる編集から学習し、音声プロファイルを徐々に改善します。

使用しない場合

• 最初のプロファイルを作成するとき（scribe:voice-extract を使用）
• プロファイルを変更せずにテキストをレビューするとき（ scribe:voice-review を使用）

方法：3 段階の比較

すべてのコンテンツは、次の 3 段階を経ます。

1. レビュー前：生成された生の出力（レビューボットによるレビュー前）
2. レビュー後：ユーザーが提案された修正を承認または却下した後
3. 編集後：ユーザーが手作業で編集した最終版

学習エージェントは、ユーザーが変更したパターンを特定するため、段階 2 と 3（レビュー後と編集後）を比較します。 こうしたパターンをもとに、文体やルールを更新します。

基本ルール

1. 追加ではなく、磨き上げる：新しいパターンをカバーするために既存のルールを修正します。ルールが肥大化すると、出力の質が低下します。
2. 適用範囲を明確にする：文体固有のパターンは文体に、普遍的なパターンはライティングルールまたはエージェントに反映します。
3. 矛盾にフラグを立てる：コンテンツ間で反対のパターンが見つかった場合、ユーザーに解決を求めます。
4. エビデンスのしきい値：パターンをルールにするには、3 件以上の実例（または既存の蓄積エントリーと一致する 1～2 件の実例）が必要です。
5. 検出されやすさ：構造の変更は AI による検出可能性を高めます。ライティングレベルの変更は中立です。ライティングレベルの更新を優先してください。
6. ルール数の確認：いずれかのセクションに 8 件以上のルールがある場合は、統合を提案します。

必須の進捗項目

1. voice-learn:snapshots-loaded - 3 段階すべてを読み込み済み
2. voice-learn:diff-analyzed - 変更を分類済み
3. voice-learn:accumulator-checked - 以前のパターンを確認済み
4. voice-learn:proposals-generated - 更新を提案済み
5. voice-learn:user-approved - ユーザーが変更を承認済み

ステップ 1：スナップショットを読み込む

@modules/snapshot-management を読み込みます

PROFILE_DIR="$HOME/.claude/voice-profiles/{name}"
SNAP_DIR="$PROFILE_DIR/learning/snapshots"

# Find the most recent snapshot set
# Format: {piece-name}-{timestamp}-{stage}.md

対象のコンテンツについて、3 段階すべてを読み込みます。

ステップ 2：差分の分析

@modules/pattern-analysis を読み込みます

レビュー後と編集後を比較します。すべての変更を分類します。

分類	例
トーンの調整	主張を和らげる、婉曲表現を加える
音声の挿入	括弧書き、余談、ユーモアを加える
構成の変更	段落を分割する、順序を入れ替える
精度の向上	曖昧な表現を具体的な表現に置き換える
削除	冗長な表現や装飾的な表現を削除する
追加	背景情報、例、手掛かりを加える

ステップ 3：蓄積データを確認する

learning/accumulator.json を読み込みます：

{
  "patterns": [
    {
      "id": "pat-001",
      "category": "tone_adjustment",
      "description": "Softens confident claims about tool capabilities",
      "instances": [
        {"piece": "blog-post-1", "date": "2026-04-08", "diff": "..."}
      ],
      "target": "register",
      "status": "accumulating",
      "first_seen": "2026-04-08",
      "last_seen": "2026-04-08"
    }
  ],
  "staleness_threshold_days": 30
}

新しい変更を既存のパターンと照合します。

• 意味的な類似性（同じ分類で、説明が類似している）
• 一致するパターンがある場合：実例を追加し、しきい値に達したか確認する
• 一致するパターンがない場合：新しい蓄積エントリーを作成する

ステップ 4：提案を生成する

しきい値に達したパターン（3 件以上の実例、または 2 件以上の実例を含む過去の蓄積エントリーと一致する 1～2 件の実例）について、次のようにします。

適用（十分なエビデンスがある場合）

## Proposed Update

**Pattern**: {description}
**Target**: {register file or craft-rules.md}
**Evidence**: {N instances across M pieces}

| Piece | Date | Change Made |
|-------|------|-------------|
| ... | ... | ... |

**Proposed edit**:
- File: {path}
- Section: {section name}
- Current: "{current text or 'new addition'}"
- Proposed: "{new text}"

保留（エビデンスが不十分な場合）

今回の実例を追加して、蓄積データに登録します。次のように報告します。

Holding: "{pattern description}" (N instances, need 3+)

矛盾

新しいパターンが既存の蓄積エントリーと矛盾する場合：

Contradiction detected:
- Existing: "{accumulator pattern}"
- New: "{contradicting pattern}"
- Resolution required: user must choose

ステップ 5：ユーザーの承認

提案をユーザーに提示します：

Learning found N patterns ready to apply:

[1] {pattern}: {proposed change}
    Evidence: {N instances}
    [a]pply / [s]kip / [v]iew evidence?

[2] ...

承認された変更を対象ファイルに適用します。

古さの判定

蓄積データ内のパターンは、staleness_threshold_days（既定値は 30）日後に期限切れになります。この期間内にパターンが再び現れなかった場合、それは音声の特性というより、一度限りの好みである可能性が高いです。

学習を行うたびに、古いエントリーを削除します。

# Remove patterns older than threshold with < 3 instances

スナップショットの取得

音声レビューが完了すると、学習システムが自動的にスナップショットを取得します。スナップショットの命名規則：

{piece-filename}-{YYYYMMDD-HHMMSS}-pre-review.md
{piece-filename}-{YYYYMMDD-HHMMSS}-post-review.md
{piece-filename}-{YYYYMMDD-HHMMSS}-post-edit.md

ユーザーが手作業での編集を終えた後に /voice-learn を実行すると、編集後のスナップショットが取得されます。

完了条件

• スナップショットを読み込み、比較した
• 変更を分類した
• 蓄積データを確認し、更新した
• しきい値に達したパターンについて提案を生成した
• ユーザーが提案を承認または却下した
• 承認された変更をプロファイルファイルに適用した
• 古い蓄積エントリーを削除した