Voice Learn

Voice Learning Skill

Learn from user edits to improve the voice profile over time.

Method: Three-Stage Comparison

Every piece flows through three stages: 1. Pre-review: Raw generation output (before review agents) 2. Post-review: After user accepts/rejects advisory fixes 3. Post-edit: User's manually edited final version

The learning agent compares stages 2 and 3 (post-review vs post-edit) to identify patterns in what the user changed. These patterns inform register and rule updates.

Core Rules

1. Sharpen, don't add: Modify existing rules to cover new patterns. Rule bloat degrades output. 2. Tag specificity: Register-specific patterns go to registers. Universal patterns go to craft rules or agents. 3. Flag contradictions: Opposite patterns across pieces require user resolution. 4. Evidence threshold: Patterns need 3+ instances (or 1-2 matching existing accumulator entries) before becoming rules. 5. Detection surface: Structural changes increase AI detectability. Craft-level changes are neutral. Prefer craft-level updates. 6. Rule count check: Suggest consolidation if any section has 8+ rules.

Required TodoWrite Items

1. voice-learn:snapshots-loaded - All three stages read 2. voice-learn:diff-analyzed - Changes categorized 3. voice-learn:accumulator-checked - Prior patterns reviewed 4. voice-learn:proposals-generated - Updates proposed 5. voice-learn:user-approved - Changes accepted by user

Step 1: Load Snapshots

Load: @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

Read all three stages for the target piece.

Step 2: Diff Analysis

Load: @modules/pattern-analysis

Compare post-review vs post-edit. Categorize every change:

Step 3: Check Accumulator

Read 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
}

Match new changes against existing patterns:

• Semantic similarity (same category + similar description)
• If match found: merge instance, check if threshold reached
• If no match: create new accumulator entry

Step 4: Generate Proposals

For patterns that reach threshold (3+ instances or 1-2 matching prior accumulator entries with 2+ instances):

Apply (strong evidence)

## 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}"

Hold (insufficient evidence)

Add to accumulator with current instances. Report:

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

Contradictions

If a new pattern contradicts an existing accumulator entry:

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

Step 5: User Approval

Present proposals to user:

Learning found N patterns ready to apply:

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

[2] ...

Apply approved changes to the target files.

Staleness

Patterns in the accumulator expire after staleness_threshold_days (default 30). If a pattern hasn't recurred within that window, it was likely a one-off preference rather than a voice trait.

On each learning pass, prune stale entries:

# Remove patterns older than threshold with < 3 instances

Snapshot Capture

The learning system captures snapshots automatically when voice-review completes. Snapshot naming:

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

The post-edit snapshot is captured when the user runs /voice-learn after finishing their manual edits.

Exit Criteria

• Snapshots loaded and compared
• Changes categorized
• Accumulator checked and updated
• Proposals generated for threshold patterns
• User approved/rejected proposals
• Approved changes applied to profile files
• Stale accumulator entries pruned

Pattern Analysis Module

Analyze diffs between post-review and post-edit snapshots to extract recurring edit patterns.

Diff Categories

Analysis Prompt

Compare these two versions of the same text:

VERSION A (post-review, before manual edits):
{post_review_text}

VERSION B (post-edit, after manual edits):
{post_edit_text}

For each change the writer made:
1. Identify the specific edit (what changed)
2. Categorize it (from the categories above)
3. Describe the pattern (what principle drove this edit?)
4. Assess specificity: is this a general writing preference
   or specific to this voice?

Focus on RECURRING patterns, not one-off fixes. If the same
type of edit appears 2+ times, that's a voice signal.

Output as a list of patterns with evidence.

Pattern Matching Against Accumulator

For each identified pattern, check the accumulator:

def match_pattern(new_pattern, accumulator):
    """Match using category + semantic similarity."""
    for existing in accumulator["patterns"]:
        if existing["category"] == new_pattern["category"]:
            # Semantic similarity check (same intent?)
            if similar_description(existing, new_pattern):
                return existing  # Merge with this entry
    return None  # New pattern

Evidence Requirements

Output Format

{
  "patterns_found": [
    {
      "category": "tone_adjustment",
      "description": "Softens confident claims about capabilities",
      "instances": [
        {"line": 12, "before": "...", "after": "..."},
        {"line": 34, "before": "...", "after": "..."}
      ],
      "recommendation": "apply|hold|discard",
      "target": "register|craft-rules|prose-reviewer",
      "proposed_edit": "..."
    }
  ]
}

Snapshot Management Module

Capture and organize text snapshots for the learning loop.

Snapshot Stages

File Naming

{piece-name}-{YYYYMMDD-HHMMSS}-{stage}.md

Example:

blog-api-design-20260410-143022-pre-review.md
blog-api-design-20260410-143022-post-review.md
blog-api-design-20260410-145511-post-edit.md

Capture Commands

Pre-review (automatic)

Called by voice-generate after producing text:

SNAP_DIR="$HOME/.claude/voice-profiles/$PROFILE/learning/snapshots"
PIECE_NAME="$1"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
cp "$OUTPUT_FILE" "$SNAP_DIR/${PIECE_NAME}-${TIMESTAMP}-pre-review.md"

Post-review (automatic)

Called by voice-review after user completes advisory decisions:

cp "$REVIEWED_FILE" "$SNAP_DIR/${PIECE_NAME}-${TIMESTAMP}-post-review.md"

Post-edit (user-triggered)

User runs /voice-learn after making manual edits:

cp "$EDITED_FILE" "$SNAP_DIR/${PIECE_NAME}-${TIMESTAMP}-post-edit.md"

Snapshot Sets

A complete set has all three stages with matching piece-name and timestamp prefix. Incomplete sets (missing post-edit) are ignored by the learning agent until completed.

Manifest Tracking

Update manifest.json learning section:

{
  "learning": {
    "snapshot_count": 12,
    "complete_sets": 4,
    "last_capture": "2026-04-10",
    "last_learning_pass": "2026-04-09"
  }
}

Cleanup

Snapshots older than 90 days with completed learning passes can be archived or deleted. The accumulator retains the pattern evidence independent of raw snapshots.