Learn from user edits to improve the voice profile over time.
When NOT To Use
Building the first profile (use scribe:voice-extract)
Reviewing text without changing the profile (use
scribe:voice-review)
Method: Three-Stage Comparison
Every piece flows through three stages:
Pre-review: Raw generation output (before review agents)
Post-review: After user accepts/rejects advisory fixes
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
Sharpen, don't add: Modify existing rules to cover new
patterns. Rule bloat degrades output.
Tag specificity: Register-specific patterns go to
registers. Universal patterns go to craft rules or agents.
Flag contradictions: Opposite patterns across pieces
require user resolution.
Evidence threshold: Patterns need 3+ instances (or 1-2
matching existing accumulator entries) before becoming rules.
Detection surface: Structural changes increase AI
detectability. Craft-level changes are neutral. Prefer
craft-level updates.
Rule count check: Suggest consolidation if any section
has 8+ rules.
Required TodoWrite Items
voice-learn:snapshots-loaded - All three stages read
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:
Category
Example
Tone adjustment
Softened a claim, added hedge
Voice insertion
Added parenthetical, aside, humor
Structure change
Broke paragraph, reordered
Precision edit
Replaced vague with specific
Deletion
Removed fluff or decoration
Addition
Added context, example, anchor
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: