# Personalization Engine

> Central hub for managing user preferences, learning patterns, and adapting skill behavior based on historical feedback. Enables "tell me once" paradigm where the system remembers and adapts.

- Skill: `diegosouzapw/personalization-engine` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/personalization-engine`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/personalization-engine/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/diegosouzapw/personalization-engine

---


# Personalization Engine Skill

**Purpose:** Central preference management that enables skills to learn from user feedback, persist decisions across sessions, and adapt behavior based on individual patterns.

**When to use:**
- User asks about their preferences ("what have you learned about me?")
- User wants to adjust confidence thresholds
- User says "don't show this again" or "remember this preference"
- Skills need to read/write user preferences
- User wants to see personalization analytics

**Key Innovation:** "Tell me once" paradigm - decisions persist across sessions, skills learn and adapt.

**Location:** `~/.claude/user-preferences.json` (global, not per-project)

---

## The Personalization Problem

### Without Personalization

**Typical experience:**
```
Session 1:
User: "Skip that suggestion"
Claude: [Suggestion hidden for this session]

Session 2:
User: "Why are you showing me that again?!"
Claude: [No memory of previous decision]
```

**Problems:**
- Users repeat same decisions session after session
- Skills don't learn from feedback
- No persistence of "don't show again" choices
- Generic suggestions that don't match user style
- **40% productive time lost** to re-establishing context

### With Personalization Engine

**New experience:**
```
Session 1:
User: "Skip that suggestion"
Claude: [Records: user skipped 'verbose-logging' - now at 3 skips]
        "Got it. I've noted you prefer to skip verbose logging suggestions.
         After 3 skips, I won't suggest this again unless you ask."

Session 2:
Claude: [Reads preferences, sees 'verbose-logging' skipped 3x]
        [Automatically filters out verbose logging suggestions]
        [User never sees it again]

User: "Why don't you suggest verbose logging?"
Claude: "You've skipped verbose logging suggestions 3 times, so I stopped showing them.
         Say 'reset verbose-logging preference' if you'd like to see them again."
```

**Benefits:**
- "Tell me once" → System remembers forever
- Skills learn from accept/reject/skip patterns
- Confidence thresholds adapt to user style
- Personalized suggestions based on history
- Transparency: User can see what system learned

---

## Operation 1: Read User Preferences

**User Queries:**
- "What are my preferences?"
- "Show my personalization settings"
- "What have you learned about me?"
- "Show my skill usage analytics"

### Reading Steps

1. **Check for preferences file:**
   ```bash
   # Check if preferences file exists
   ls ~/.claude/user-preferences.json 2>/dev/null
   ```

2. **Load preferences:**
   - If exists: Parse JSON and return relevant sections
   - If not exists: Return defaults with "no preferences recorded yet" message

3. **Return formatted summary:**

### Response Template: Preferences Summary

```markdown
## Your Personalization Profile

**Learning Period:** 45 days (since 2025-11-01)
**Total Decisions Tracked:** 234
**Overall Acceptance Rate:** 72%

---

### Profile Settings

| Setting | Value |
|---------|-------|
| Experience Level | Intermediate |
| Primary Languages | TypeScript, Python |
| Proactivity Level | Medium |
| Preferred Workflow | Wizard |

---

### Confidence Thresholds

| Action | Your Threshold | Default | Difference |
|--------|---------------|---------|------------|
| Auto-apply | 95% | 90% | +5% (more conservative) |
| Suggest prominently | 75% | 75% | Same |
| Show as optional | 50% | 50% | Same |
| Hide below | 30% | 25% | +5% (less noise) |

---

### Top Skills by Usage

| Rank | Skill | Invocations | Last Used |
|------|-------|-------------|-----------|
| 1 | version-management | 78 | Today |
| 2 | commit-readiness-checker | 56 | Today |
| 3 | security-scanner | 34 | Yesterday |
| 4 | test-generator | 28 | 3 days ago |
| 5 | standards-enforcer | 22 | Today |

---

### Learned Preferences

**High Acceptance (>75%):**
- Null checks before dereferencing (92%)
- Conventional commit messages (88%)
- TypeScript strict mode (85%)

**Low Acceptance (<40%):**
- Early returns (23%) - You prefer explicit conditionals
- Verbose logging (12%) - You prefer minimal logging
- JSDoc comments (35%) - You prefer inline comments

**Permanently Skipped:**
- sequential-thinking MCP setup (skipped 3x, permanent)
- Git hook installation (skipped 2x, permanent)

---

### Recommendations

Based on your patterns:

1. **workflow-analyzer** (78% confidence)
   - You commit frequently (15 commits this week)
   - This skill could identify optimization patterns
   - Estimated time: 2 minutes to enable

2. **Raise auto-apply threshold to 97%** (65% confidence)
   - You rarely accept auto-applied changes
   - Higher threshold = fewer surprises

Would you like to adjust any of these settings?
```

### Response Template: No Preferences Yet

```markdown
## Personalization Status

**Status:** No preferences recorded yet

You're starting fresh! As you use Claude Code, I'll learn your preferences:

**What I'll Learn:**
- Which suggestions you accept vs reject
- Your preferred coding style patterns
- Which recommendations you skip
- Your confidence threshold preferences

**How It Works:**
1. Use skills normally (commit-readiness, security-scanner, etc.)
2. Accept, reject, or skip suggestions
3. Preferences are saved to `~/.claude/user-preferences.json`
4. Future sessions adapt based on your history

**Privacy:**
- All data stored locally on your machine
- Never synced to cloud
- You can view, edit, or delete anytime

Start using skills and I'll begin learning your preferences!
```

---

## Operation 2: Update Preferences

**User Queries:**
- "Remember that I prefer X"
- "Don't show this suggestion again"
- "Set my proactivity level to low"
- "Update my confidence threshold to 90%"
- "Skip this recommendation permanently"

### Update Types

#### Type 1: Direct Preference Setting

User explicitly sets a preference.

**Example:**
```
User: "Set my proactivity level to low"

Response:
✅ Updated proactivity level: medium → low

What this means:
- Only high-confidence suggestions will be shown
- Optional suggestions will be hidden
- Minimal interruptions during workflow

To revert: Say "set proactivity to medium"
```

#### Type 2: Feedback-Based Learning

Skills report user decisions, engine updates acceptance rates.

**Feedback Protocol:**

```typescript
interface PreferenceFeedback {
  skill: string;         // e.g., "standards-enforcer"
  category: string;      // e.g., "coding-style"
  item: string;          // e.g., "early-returns"
  action: "accept" | "reject" | "skip" | "dont-show-again";
  context?: string;      // Optional context
  timestamp: string;     // ISO date
}
```

**Learning Algorithm:**

```
New acceptance rate = (old_rate × old_samples + new_value) / (old_samples + 1)

Where:
- accept = 1.0
- reject = 0.0
- skip = 0.3 (weak negative signal)

Example:
- Old rate: 0.60 (60%), 10 samples
- User rejects suggestion
- New rate: (0.60 × 10 + 0.0) / 11 = 0.545 (54.5%)
```

#### Implicit Learning Signals (v4.23.0)

**Enhancement:** Detect signal strength from user language, not just explicit actions.

**Signal Taxonomy:**

| Signal Type | Keywords | Value | Weight | Example |
|-------------|----------|-------|--------|---------|
| **Strong Positive** | "exactly", "perfect", "love it", "that's great" | 1.0 | 2x | "That's exactly what I wanted!" → 2.0 |
| **Enthusiasm** | "wow", "awesome", "brilliant", "yes!" | 1.0 | 1.5x | "Wow, that's really cool" → 1.5 |
| **Neutral Accept** | (default accept) | 1.0 | 1x | (silence = acceptance) → 1.0 |
| **Weak Negative** | "skip", "not now", "later" | 0.3 | 1x | "Skip that" → 0.3 |
| **Correction** | "actually", "instead", "not that", "wrong" | 0.0 | 2x | "Actually, not that way" → -2.0 (double negative) |
| **Strong Negative** | "never", "don't", "stop", "no" | 0.0 | 2x | "Never do that" → -2.0 (double negative) |

**Enhanced Learning Algorithm:**

```
Base signal = action value (1.0, 0.3, or 0.0)
Detected weight = keyword multiplier (1x, 1.5x, or 2x)
Effective signal = base × weight

New acceptance rate = (old_rate × old_samples + effective_signal) / (old_samples + 1)

Examples:

1. Strong positive: "That's exactly what I wanted!"
   - Base: 1.0 (accept)
   - Weight: 2x (strong positive keyword)
   - Effective: 2.0
   - New rate: (0.60 × 10 + 2.0) / 11 = 0.727 (72.7%)

2. Correction: "Actually, let's not do early returns"
   - Base: 0.0 (reject)
   - Weight: 2x (correction keyword)
   - Effective: 0.0 (double weight on rejection = faster learning)
   - New rate: (0.60 × 10 + 0.0) / 11 = 0.545, then apply -1x correction
   - Adjusted: 0.545 - 0.1 = 0.445 (44.5%)

3. Neutral skip: "Skip that"
   - Base: 0.3 (skip)
   - Weight: 1x (no keyword)
   - Effective: 0.3
   - New rate: (0.60 × 10 + 0.3) / 11 = 0.573 (57.3%)
```

**Correction Signal Detection (v4.23.0):**

Detects when user immediately edits AI-generated content:

**Pattern:**
```
AI generates code → User edits within 1 minute → Correction signal
```

**Action:**
1. Record pattern: "Don't generate [pattern] for [file type]"
2. Apply high negative weight (2x)
3. Add to "learned patterns" with correction timestamp

**Example:**
```markdown
## Correction Detected

**What happened:**
1. I suggested: `if (!condition) return;`
2. You changed it to: `if (condition) { ... }`

**What I learned:**
- Pattern: early-returns
- File type: typescript
- Your preference: explicit conditionals
- Confidence: High (correction signal)

**Future behavior:**
I'll avoid suggesting early returns in TypeScript files. Current acceptance rate for early-returns: 45% → 25% (correction applied).
```

**Keyword Detection Process:**

1. **On user message:** Scan for signal keywords
2. **Match patterns:** Check against signal taxonomy
3. **Calculate weight:** Apply multiplier (1x, 1.5x, 2x)
4. **Update preferences:** Use enhanced algorithm
5. **Provide feedback:** Show what was learned

**Privacy:**
- Keyword matching only (no full message storage)
- Only sentiment detected (not message content)
- User can disable: "Don't detect implicit signals"

#### File-Context Memory (v4.24.0)

**Enhancement:** Tag preferences with file paths - recall patterns when editing the same file.

**The Problem:**
```
Session 1: User edits CLAUDE.md, prefers sentence-case headers
Session 2: User edits README.md, prefers title-case headers
Session 3: User edits CLAUDE.md again
          → System suggests title-case (wrong context!)
```

**The Solution:**
Tag preferences with file path or file pattern, recall when editing same file.

**File-Context Tagging:**

| Context Level | Pattern | Example |
|---------------|---------|---------|
| **Exact File** | Full path | `/path/to/CLAUDE.md` → sentence-case headers |
| **File Pattern** | Glob pattern | `*.md` → markdown linting rules |
| **Directory** | Directory path | `/docs/` → documentation style |
| **File Type** | Extension | `.ts` → TypeScript conventions |

**Storage Format:**

```json
{
  "fileContextPreferences": {
    "CLAUDE.md": {
      "header-style": {
        "preference": "sentence-case",
        "acceptanceRate": 0.95,
        "samples": 12,
        "lastUsed": "2025-12-22T10:30:00Z"
      }
    },
    "*.md": {
      "line-length": {
        "preference": "no-limit",
        "acceptanceRate": 0.80,
        "samples": 25
      }
    },
    "docs/**/*.md": {
      "emoji-usage": {
        "preference": "section-headers-only",
        "acceptanceRate": 0.90,
        "samples": 15
      }
    }
  }
}
```

**Matching Priority:**

1. **Exact file path** (highest priority)
2. **Specific glob pattern** (e.g., `docs/**/*.md`)
3. **General file type** (e.g., `*.md`)
4. **Directory pattern** (e.g., `/docs/`)
5. **Global preference** (fallback)

**Trigger Pattern:**

```
User edits file → System checks fileContextPreferences
                → Loads preferences for matching patterns
                → Applies to suggestions for this file
```

**Example:**

```markdown
## File-Context Detected

**File:** CLAUDE.md
**Context loaded:**
- Header style: sentence-case (95% acceptance, 12 samples)
- Line length: no-limit (80% acceptance, inherited from *.md)
- Emoji usage: section-headers-only (90% acceptance, inherited from docs/)

**Applying these preferences to suggestions for this file.**
```

**Learning:**

When user accepts/rejects suggestion while editing a file:

1. Update global preference (as before)
2. **Also tag with current file context**
3. Store both general + file-specific learning

**Conflict Resolution:**

If file-context preference conflicts with global:
- **File-context wins** (more specific)
- Show user: "Using CLAUDE.md preference (sentence-case) instead of global (title-case)"

**Commands:**

```
"Show file-context preferences for CLAUDE.md"
"What have you learned about this file?"
"Reset file-context for *.md"
"Disable file-context memory"
```

#### Recovery Pattern Learning (v4.24.0)

**Enhancement:** Learn from failure → success sequences to proactively suggest solutions.

**The Problem:**
```
User tries approach A → Fails
User tries approach B → Fails
User tries approach C → Success!
Next time: System doesn't remember C was the winner
```

**The Solution:**
Track task → attempt → outcome sequences, remember successful approaches.

**Recovery Pattern Detection:**

```
Pattern: Multiple attempts on same task before success
Trigger: 2+ failures followed by success within same session
Action: Record the successful approach as "proven solution"
```

**Pattern Structure:**

```json
{
  "recoveryPatterns": {
    "fix-typescript-import-error": {
      "context": {
        "errorType": "typescript-import",
        "attempts": 3,
        "failedApproaches": [
          "relative-path-import",
          "namespace-import"
        ],
        "successfulApproach": "default-import-with-type",
        "confidence": "high"
      },
      "metadata": {
        "firstAttempt": "2025-12-22T10:00:00Z",
        "resolved": "2025-12-22T10:15:00Z",
        "timeTaken": "15 minutes",
        "fileType": "typescript",
        "successRate": 1.0,
        "timesApplied": 3
      }
    }
  }
}
```

**Detection Logic:**

1. **Failure Detection:**
   - Test fails
   - Build error
   - User says "that didn't work", "still broken", "try again"
   - User immediately edits generated code (correction signal)

2. **Attempt Tracking:**
   - Same task attempted multiple times within 30 minutes
   - Different approaches each time
   - Track what was tried

3. **Success Detection:**
   - Tests pass after failures
   - User says "that worked!", "fixed!", "success"
   - No further edits after 5 minutes (silent success)

4. **Pattern Recording:**
   - Store: task type, failed approaches, successful approach
   - Tag with: file type, error type, context
   - Confidence: high (proven by recovery)

**Proactive Suggestions:**

Next time similar task is attempted:

```markdown
## Recovery Pattern Detected

**Task:** Fixing TypeScript import error
**I remember:** You solved this before in 3 attempts

**Failed approaches (avoid these):**
1. ❌ relative-path-import (didn't work)
2. ❌ namespace-import (didn't work)

**Successful approach (use this):**
✅ default-import-with-type (worked after 15 minutes)

**Apply proven solution?** This worked for you last time.
```

**Learning Enhancement:**

Recovery patterns have **higher confidence** than single-try learnings:
- Regular acceptance: 75% confidence
- Recovery pattern: 95% confidence (proven through struggle)

**Why this works:**

Hard-won solutions have higher value:
- User invested time (15 minutes in example)
- Multiple approaches tested
- Success validated through comparison
- **Psychological:** Struggling → success creates strong memory

**Commands:**

```
"Show recovery patterns"
"What solutions have I found through trial-and-error?"
"How did I solve [task] last time?"
"Forget recovery pattern for [task]"
```

#### Workflow Gap Detection (v4.25.0)

**Enhancement:** Identify related tasks that should be linked - automate repetitive workflows.

**The Problem:**
```
Pattern detected over 20 commits:
1. User edits version.json
2. User runs sync-version.sh
3. User edits CHANGELOG.md
4. User commits

Every single time, same sequence. Manual, repetitive, forgettable.
```

**The Solution:**
Detect workflow patterns from commit history, suggest automation or linking.

**Gap Detection:**

| Gap Type | Pattern | Suggestion |
|----------|---------|------------|
| **Sequential Tasks** | A always followed by B | "Link these tasks?" |
| **Forgotten Steps** | A → C (B missing) | "You usually do B between A and C" |
| **Manual Repetition** | Same sequence 5+ times | "Automate this workflow?" |
| **Context Switch** | Edit file A, then edit file B (unrelated) | "Consider grouping related edits" |

**Detection Logic:**

**1. Sequential Pattern Detection:**

```
Analyze last 50 commits:
- Find sequences: [edit version.json] → [run script] → [edit CHANGELOG]
- Frequency: 18/20 commits (90%)
- Time gap: Average 2 minutes between steps
→ Pattern detected: version-bump-workflow
```

**2. Forgotten Step Detection:**

```
Analyze current session:
- User edited version.json
- User edited CHANGELOG.md
- Missing: sync-version.sh (usually runs between these)
→ Gap detected: "Did you forget to run sync-version.sh?"
```

**3. Repetition Analysis:**

```
Same workflow detected 15 times:
1. git add .
2. git commit -m "..."
3. git push origin main

Time: 1-2 minutes per execution
→ Suggestion: "Create alias or git hook for this sequence?"
```

**Storage Format:**

```json
{
  "workflowPatterns": {
    "version-bump-workflow": {
      "steps": [
        {
          "action": "edit",
          "target": "version.json",
          "confidence": 0.95
        },
        {
          "action": "run",
          "target": "sync-version.sh",
          "confidence": 0.90
        },
        {
          "action": "edit",
          "target": "CHANGELOG.md",
          "confidence": 0.95
        },
        {
          "action": "commit",
          "pattern": "^(feat|fix|docs):",
          "confidence": 0.88
        }
      ],
      "metadata": {
        "frequency": 18,
        "totalCommits": 20,
        "patternStrength": 0.90,
        "avgTimePerStep": "2 minutes",
        "lastOccurrence": "2025-12-22T14:30:00Z"
      }
    }
  },
  "detectedGaps": {
    "missing-sync-script": {
      "workflow": "version-bump-workflow",
      "missingStep": "sync-version.sh",
      "frequency": 3,
      "impact": "medium"
    }
  }
}
```

**Proactive Detection:**

```markdown
## 🔗 Workflow Gap Detected

**Pattern:** version-bump-workflow
**Frequency:** 18/20 commits (90%)

**Your usual sequence:**
1. ✓ Edit version.json
2. ⚠️ Run sync-version.sh ← **You haven't done this yet**
3. ? Edit CHANGELOG.md (expected next)
4. ? Commit changes

**Suggestion:** Run sync-version.sh now to stay on pattern?

[Run now] [Skip this time] [Don't remind me]
```

**Automation Suggestions:**

After detecting high-frequency patterns (10+ occurrences):

```markdown
## 🤖 Automation Opportunity

**Workflow:** version-bump-workflow
**Frequency:** 18 times (manually repeated)
**Time cost:** ~36 minutes total (2 min × 18)

**I can help automate this:**

Option 1: Pre-commit hook
  - Auto-runs sync-version.sh before commit
  - Validates version consistency

Option 2: Bash script wrapper
  - Single command: ./bump-version.sh 4.25.0
  - Handles all 4 steps automatically

Option 3: Git alias
  - git bump-version "4.25.0"
  - Custom alias for this workflow

[Show me how] [Not now] [Never suggest for this workflow]
```

**Commands:**

```
"Show workflow patterns"
"What workflows have you detected?"
"Show gaps in current workflow"
"Suggest automation for [workflow]"
"Forget workflow pattern [name]"
```

#### Adaptive Threshold Tuning (v4.25.0)

**Enhancement:** Continuous micro-adjustments to confidence thresholds based on actual user behavior.

**The Problem:**
```
Current: Manual threshold adjustments
- User sets autoApply = 95%
- System uses 95% forever
- Even if user rejects 80% of auto-applied suggestions
→ Static threshold, not adapting to reality
```

**The Solution:**
Continuously monitor acceptance rates by confidence level, adjust thresholds automatically.

**Current (v3.10.0) AI-Suggested Tuning:**
- Runs every 7 days
- Manual review required
- Suggests threshold changes
- User must approve

**Enhanced (v4.25.0) Adaptive Tuning:**
- Runs continuously
- Micro-adjustments (±1-2%)
- No user approval needed
- Transparent feedback

**Tuning Logic:**

**1. Confidence Band Analysis:**

```
Analyze suggestions at each confidence level:

90-95%: 20 suggestions, 12 accepted (60% acceptance)
85-90%: 15 suggestions, 13 accepted (87% acceptance)
80-85%: 10 suggestions, 9 accepted (90% acceptance)

Observation: 85-90% band has HIGHER acceptance than 90-95%
→ Threshold too conservative, or 90-95% suggestions are wrong type
```

**2. Micro-Adjustment Rules:**

| Condition | Action | Magnitude |
|-----------|--------|-----------|
| 5 consecutive rejections at confidence X | Lower threshold by 2% | Gentle |
| 80%+ rejection rate in band | Lower threshold by 5% | Moderate |
| 90%+ acceptance rate in band | Raise threshold by 2% | Gentle |
| 95%+ acceptance, 20+ samples | Raise threshold by 5% | Moderate |

**3. Adjustment Limits:**

Safety constraints:
- **Max change per day:** ±10%
- **Min threshold:** 30% (never go below)
- **Max threshold:** 98% (never require perfection)
- **Cooldown:** 24 hours between major adjustments (>5%)

**Example Adaptive Flow:**

```
Day 1: autoApply threshold = 95%
       Suggestions at 95%+: 10 generated
       User rejects: 7/10 (70% rejection)

Day 2: System analyzes: "70% rejection is too high"
       Adjustment: 95% → 97% (+2%, gentle)
       Notification: "Raised autoApply to 97% (you rejected 70% at 95%)"

Day 3: Suggestions at 97%+: 5 generated
       User accepts: 4/5 (80% acceptance)

Day 5: System analyzes: "80% acceptance is good"
       No adjustment (stable)

Day 10: Suggestions at 97%+: 20 generated
        User accepts: 19/20 (95% acceptance)

Day 11: System analyzes: "95% acceptance, could be more permissive"
        Adjustment: 97% → 95% (-2%, gentle)
        Notification: "Lowered autoApply to 95% (you accept 95% at this level)"
```

**Storage Format:**

```json
{
  "adaptiveThresholds": {
    "autoApply": {
      "current": 95,
      "original": 95,
      "history": [
        {
          "timestamp": "2025-12-22T10:00:00Z",
          "value": 95,
          "reason": "user-set"
        },
        {
          "timestamp": "2025-12-23T10:00:00Z",
          "value": 97,
          "reason": "high-rejection-rate",
          "data": {
            "acceptanceRate": 0.30,
            "samples": 10
          }
        },
        {
          "timestamp": "2025-12-30T10:00:00Z",
          "value": 95,
          "reason": "high-acceptance-rate",
          "data": {
            "acceptanceRate": 0.95,
            "samples": 20
          }
        }
      ],
      "lastAdjustment": "2025-12-30T10:00:00Z",
      "adjustmentCount": 2
    }
  },
  "confidenceBandStats": {
    "95-100": {
      "suggestions": 30,
      "accepted": 27,
      "acceptanceRate": 0.90,
      "trend": "stable"
    },
    "90-95": {
      "suggestions": 45,
      "accepted": 39,
      "acceptanceRate": 0.87,
      "trend": "increasing"
    }
  }
}
```

**Transparency:**

Every adjustment is logged and explained:

```markdown
## 📊 Threshold Adjusted

**Threshold:** autoApply
**Change:** 95% → 93% (-2%)
**Reason:** High acceptance rate at this level

**Data:**
- Suggestions at 95%+: 25 in last 7 days
- Your acceptance: 24/25 (96%)
- Confidence: You're comfortable with slightly lower threshold

**Impact:** More suggestions will auto-apply
**Revert:** "Set autoApply to 95%" to undo

[View adjustment history] [Disable adaptive tuning]
```

**User Control:**

```
"Disable adaptive tuning"
"Enable adaptive tuning"
"Show threshold adjustment history"
"Revert threshold changes"
"Lock autoApply threshold at 95%"
"Show confidence band statistics"
```

**Safety Features:**

- **Preview mode:** Test adjustments for 24 hours before applying
- **Undo:** Revert to any previous threshold
- **Lock:** Prevent adjustments to specific thresholds
- **Notification:** Always inform user of changes
- **Limits:** Max ±10% per day, never below 30% or above 98%

**Integration with v4.23.0 & v4.24.0:**

```
Adaptive tuning uses:
- Implicit signals (v4.23.0): Keywords boost/lower confidence scores
- File-context (v4.24.0): Adjust thresholds per file pattern
- Recovery patterns (v4.24.0): Proven solutions get lower threshold

Example:
- Recovery pattern: 95% confidence baseline
- File-context (CLAUDE.md): 97% acceptance rate
- Adaptive tuning: Lowers threshold to 93% for CLAUDE.md
→ More recovery patterns auto-applied in this context
```

**Commands:**

```
"Show adaptive tuning status"
"Disable adaptive tuning for autoApply"
"Show threshold adjustment history"
"Why did you adjust [threshold]?"
"Revert to original thresholds"
"Lock all thresholds"
```

**Threshold Rules:**

| Acceptance Rate | Status | Behavior |
|-----------------|--------|----------|
| ≥75% | High acceptance | Show prominently |
| 50-74% | Medium | Show as optional |
| 25-49% | Low | Hide by default (proactivity=high shows) |
| <25% | Very low | Never show |

#### Type 3: Skip Counter

Tracks how many times user skips a recommendation.

```
Skip 1: Note preference
Skip 2: Lower priority
Skip 3: Mark as "permanent skip" (unless user says otherwise)
```

**Response Template: Skill Skipped**

```markdown
Got it. I've noted you skipped "sequential-thinking MCP setup".

**Skip History:**
- Skip 1: 2025-12-10
- Skip 2: 2025-12-12
- Skip 3: Today (permanent skip threshold reached)

**Action:** I won't suggest this again unless you ask.

To see it again: Say "reset sequential-thinking preference"
To see all skipped items: Say "show skipped recommendations"
```

#### Type 4: Don't Show Again

Explicit "never show this" request.

**Response Template: Don't Show Again**

```markdown
✅ Marked as "don't show again": Security scanner info-level findings

**What this affects:**
- Security scanner will hide informational findings
- Only Medium, High, and Critical will be shown

**To revert:**
Say "show security scanner info-level findings again"

**All "don't show again" items:**
1. Security scanner info-level findings
2. Test coverage reminder below 80%
3. Git hook installation prompt
```

### Update Steps

1. **Parse user intent:**
   - Direct setting change?
   - Feedback on a suggestion?
   - Skip request?
   - Don't show again?

2. **Load current preferences:**
   ```bash
   cat ~/.claude/user-preferences.json
   ```

3. **Apply update:**
   - Calculate new values (if learning-based)
   - Merge with existing preferences
   - Create backup if major change

4. **Write updated preferences:**
   ```bash
   cp ~/.claude/user-preferences.json ~/.claude/user-preferences.json.backup
   # Write new content
   ```

5. **Confirm to user:**
   - Show before/after
   - Explain impact
   - Provide revert instructions

---

## Operation 3: Adaptive Threshold Management

**User Queries:**
- "Why did you show me that suggestion?"
- "Why didn't you suggest X?"
- "Make suggestions more/less frequent"
- "Explain my threshold settings"

### How Thresholds Work

**Four threshold levels:**

```
100% ─────────────────────────────────────
      │ AUTO-APPLY ZONE                  │
 95%  ├─────────────────────────────────────  autoApply threshold
      │ PROMINENT SUGGESTION ZONE        │
 75%  ├─────────────────────────────────────  suggestProminently threshold
      │ OPTIONAL SUGGESTION ZONE         │
 50%  ├─────────────────────────────────────  showAsOptional threshold
      │ LOW CONFIDENCE ZONE              │
 30%  ├─────────────────────────────────────  hideBelow threshold
      │ HIDDEN (too low confidence)      │
  0% ─────────────────────────────────────
```

**Proactivity Level Modifiers:**

| Proactivity | autoApply | prominent | optional | hide |
|-------------|-----------|-----------|----------|------|
| Low | 98% | 85% | 70% | 50% |
| Medium | 95% | 75% | 50% | 30% |
| High | 90% | 60% | 40% | 20% |

### Response Template: Threshold Explanation

```markdown
## Why You Saw That Suggestion

**Suggestion:** "Consider using early returns"
**Confidence:** 65%
**Your Threshold:** Show as optional at ≥50%

**Decision Path:**
1. Confidence (65%) < Auto-apply (95%) → Won't auto-apply
2. Confidence (65%) < Prominent (75%) → Won't show prominently
3. Confidence (65%) ≥ Optional (50%) → ✅ Show as optional
4. Confidence (65%) ≥ Hide (30%) → Don't hide

**Result:** Shown as optional suggestion

**Your History with This Pattern:**
- Acceptance rate: 23% (5 accepted, 17 rejected)
- Trend: Declining (you've rejected last 5)

**Recommendation:**
Based on your history, I could stop showing "early returns" suggestions.
Say "don't suggest early returns" to apply this.
```

### Response Template: Why Not Suggested

```markdown
## Why I Didn't Suggest X

**Pattern:** Verbose logging
**Confidence:** 45%
**Your Threshold:** Hide below 50%

**Decision Path:**
1. Confidence (45%) < Hide threshold (50%)
2. **Result:** Hidden

**Your History:**
- Acceptance rate: 12% (2 accepted, 15 rejected)
- Status: Low acceptance (auto-hidden)

**If You Want to See It:**
1. Lower your hide threshold: "set hide threshold to 40%"
2. Reset this specific preference: "reset verbose-logging preference"
3. Ask explicitly: "suggest verbose logging for this code"
```

---

## Operation 4: Skill Usage Analytics

**User Queries:**
- "Which skills do I use most?"
- "Show my usage patterns"
- "What skills should I try?"
- "Analyze my workflow"

### Analytics Response Template

```markdown
## Your Claude Code Usage Analytics

**Analysis Period:** Last 30 days
**Total Skill Invocations:** 234

---

### Usage Distribution

```
version-management      ████████████████████ 78 (33%)
commit-readiness        ██████████████ 56 (24%)
security-scanner        █████████ 34 (15%)
test-generator          ███████ 28 (12%)
standards-enforcer      █████ 22 (9%)
other                   ███ 16 (7%)
```

---

### Usage Patterns

**Peak Usage Times:**
- Most active: Weekdays 9am-12pm
- Least active: Weekends

**Workflow Pattern Detected:** Release-focused
- High version-management usage suggests frequent releases
- commit-readiness checks before every commit
- security-scanner run before deployments

**Session Characteristics:**
- Average session length: 45 minutes
- Average skills per session: 3.2
- Most common sequence: commit-readiness → version-management → security-scanner

---

### Skill Recommendations

Based on your patterns, you might benefit from:

**1. workflow-analyzer** (85% match)
- You have 15 commits this week
- Pattern: Frequent small commits
- Benefit: Identify commit pattern optimizations
- Time to enable: 2 minutes

**2. documentation-sync-checker** (72% match)
- You use version-management frequently
- Pattern: Version updates might drift from docs
- Benefit: Catch documentation staleness early
- Time to enable: 3 minutes

**3. test-generator** (more) (65% match)
- Current usage: 28 invocations
- You run security-scanner frequently
- Pattern: Security-conscious but test coverage unknown
- Benefit: Ensure test coverage matches security focus

---

### Unused Skills

You haven't tried these skills yet:
- projects-registry (multi-project tracking)
- api-debugging (API troubleshooting)
- component-finder (React/Vue component search)

Would you like me to explain any of these?
```

---

## Operation 5: Reset Preferences

**User Queries:**
- "Reset my preferences"
- "Clear preference for X"
- "Start fresh with personalization"
- "Delete my learning history"

### Reset Options

#### Option 1: Reset Specific Preference

```markdown
✅ Reset preference: early-returns

**Before:**
- Acceptance rate: 23% (low)
- Sample size: 22 decisions
- Status: Hidden by default

**After:**
- Acceptance rate: 50% (neutral)
- Sample size: 0
- Status: Will be shown normally

The system will re-learn your preference as you use it.
```

#### Option 2: Reset Category

```markdown
✅ Reset category: coding-style

**Preferences Reset:**
- early-returns
- verbose-logging
- null-checks
- type-annotations
+ 8 more

**What Happens:**
- All coding-style suggestions return to default confidence
- System will re-learn from your decisions
- Other categories (workflow, quality, etc.) unchanged
```

#### Option 3: Full Reset

```markdown
⚠️ Full Preferences Reset

This will:
- Delete ~/.claude/user-preferences.json
- Reset all learned preferences to defaults
- Clear usage analytics
- Remove all "don't show again" items
- Clear skipped recommendations list

**Backup Created:** ~/.claude/user-preferences.json.backup.2025-12-15

Are you sure? Say "confirm reset" to proceed.
```

---

## Integration Protocol for Skills

Other skills integrate with Personalization Engine using this protocol:

### Reading Preferences (Skill Start)

```markdown
## Reading User Preferences

When a skill activates, it should:

1. **Check for preferences file:**
   - If `~/.claude/user-preferences.json` exists, read relevant sections
   - If not, use defaults

2. **Load skill-specific preferences:**
   ```json
   {
     "skillSpecificPreferences": {
       "security-scanner": {
         "showInfoLevel": true,
         "autoFixLowRisk": false
       }
     }
   }
   ```

3. **Load learned preferences for relevant categories:**
   ```json
   {
     "learnedPreferences": {
       "quality": {
         "security-scan-threshold": "high"
       }
     }
   }
   ```

4. **Load confidence thresholds:**
   ```json
   {
     "confidenceThresholds": {
       "suggestProminently": 75,
       "showAsOptional": 50
     }
   }
   ```

5. **Filter suggestions:**
   - Check `dontShowAgain.items` for items to skip
   - Check `skippedRecommendations.items` for skipped items
   - Apply confidence thresholds to each suggestion
```

### Writing Feedback (After User Decision)

```markdown
## Recording User Feedback

When user accepts/rejects/skips a suggestion:

1. **Construct feedback event:**
   ```json
   {
     "timestamp": "2025-12-15T10:30:00Z",
     "skill": "standards-enforcer",
     "category": "coding-style",
     "item": "early-returns",
     "action": "rejected",
     "context": "user preferred explicit conditional"
   }
   ```

2. **Update learned preferences:**
   - Calculate new acceptance rate
   - Update sample size
   - Record trend direction

3. **Update analytics:**
   - Increment decision counter
   - Update category breakdown
   - Add to learning history (max 100 events)

4. **Update skill usage:**
   - Increment usage counter
   - Update lastUsed timestamp

5. **Write to preferences file:**
   - Create backup first
   - Write updated JSON
   - Validate JSON structure
```

### Example: Standards Enforcer Integration

```markdown
## Standards Enforcer + Personalization

**Before (v3.7.0):**
- Standards Enforcer tracks acceptance rates internally
- Learning resets each session
- No cross-skill patterns

**After (v3.8.0):**

**On Activation:**
```
1. Read ~/.claude/user-preferences.json
2. Load learnedPreferences.coding-style
3. Filter suggestions where acceptance_rate < hideBelow threshold
4. Apply confidence modifiers from learned rates
```

**On User Decision:**
```
1. User rejects "early returns" suggestion
2. Calculate new acceptance rate
3. Write feedback to preferences file
4. Update analytics
```

**Result:**
- Learning persists across sessions
- Other skills benefit from coding-style learnings
- User sees consistent behavior
```

---

## Operation 6: Project Preferences (v3.9.0)

**User Queries:**
- "Show project preferences"
- "Set project proactivity to high"
- "Override security threshold for this project"
- "Create project preferences file"
- "Why is this project using different settings?"
- "Show effective preferences" (merged view)

### The Project Override Problem

**Global preferences don't fit all projects:**
- Security-critical project needs stricter thresholds
- Learning project wants more suggestions
- Legacy project has different coding standards
- Team project needs shared conventions

**Solution:** Project-level preference overrides that merge with global.

### Merge Logic

```
Final Preference = Global + Project Override

Merge Rules:
1. Project values override global values
2. Unspecified values inherit from global
3. Deep merge for nested objects
4. Arrays are replaced (not merged)

Example:
Global: { proactivityLevel: "medium", autoApply: 95, hideBelow: 30 }
Project: { proactivityLevel: "high" }
Result: { proactivityLevel: "high", autoApply: 95, hideBelow: 30 }
```

### File Locations

```
Global (personal):
~/.claude/user-preferences.json

Project (shared with team):
.claude/project-preferences.json

Reading order:
1. Read global preferences
2. Check for project preferences
3. Deep merge (project wins)
4. Return effective preferences
```

### Creating Project Preferences

**User says:** "Create project preferences for this project"

**Steps:**
1. Check if `.claude/project-preferences.json` exists
2. If not, create from template with sensible defaults
3. Prompt user for key overrides (proactivity, security level)
4. Save to `.claude/project-preferences.json`

**Response:**

```markdown
## Project Preferences Created

**File:** .claude/project-preferences.json

I've created a project preferences file with:
- Sparse format (only overrides, inherits rest from global)
- Reason fields for documentation
- Project context section

**Current Overrides:** None (using all global settings)

**To customize:**
- "Set project proactivity to high"
- "Set project autoApply threshold to 98%"
- "Enable strict security scanning for this project"

**Team sharing:**
This file can be committed to git so your team shares the same AI behavior.
```

### Viewing Project Preferences

**User says:** "Show project preferences"

**Response Template:**

```markdown
## Project Preferences: claude-config-template

**Status:** Project overrides active
**File:** .claude/project-preferences.json

---

### Overrides from Global

| Setting | Global | Project | Reason |
|---------|--------|---------|--------|
| proactivityLevel | medium | high | Documentation project - want thorough suggestions |
| autoApply | 95% | 98% | Be conservative with auto-changes |
| security.showInfoLevel | false | true | Show all security findings |

---

### Inherited from Global (no override)

- Experience level: intermediate
- Primary languages: typescript, python
- suggestProminently: 75%
- showAsOptional: 50%
- hideBelow: 30%

---

### Project Context

**Tech Stack:**
- Languages: TypeScript, Markdown
- Frameworks: None (documentation project)
- Testing: None

**Priorities:**
- Security: medium
- Documentation: high
- Performance: low

---

**To modify:** "Set project [setting] to [value]"
**To remove override:** "Remove project override for [setting]"
**To delete all:** "Delete project preferences"
```

### Viewing Effective Preferences

**User says:** "Show effective preferences" or "What settings am I actually using?"

**Response Template:**

```markdown
## Effective Preferences (Merged View)

**Source:** Global + Project overrides

---

### Profile
| Setting | Value | Source |
|---------|-------|--------|
| experienceLevel | intermediate | Global |
| proactivityLevel | high | **Project** |
| primaryLanguages | typescript, python | Global |

### Confidence Thresholds
| Threshold | Value | Source |
|-----------|-------|--------|
| autoApply | 98% | **Project** |
| suggestProminently | 75% | Global |
| showAsOptional | 50% | Global |
| hideBelow | 30% | Global |

### Skill Settings
| Skill | Setting | Value | Source |
|-------|---------|-------|--------|
| security-scanner | showInfoLevel | true | **Project** |
| test-generator | coverageTarget | 80% | Global |

---

**Legend:**
- Global = From ~/.claude/user-preferences.json


…(truncated)