Friction Detector

Friction-to-Learning Pipeline

Overview

Detect friction signals during agent execution, track them across sessions,

and graduate recurring patterns into permanent guidance. Bridges the gap

between ephemeral session friction and durable CLAUDE.md rules.

Research backing: Claude Coach (hook-based friction detection with SQLite

storage), alirezarezvani's self-improving-agent (three-tier MEMORY to

CLAUDE.md graduation), and the ACE framework (arXiv: evolving playbooks from

execution feedback, +10.6% on agent tasks).

Current gap: LEARNINGS.md exists but requires manual aggregation via

/abstract:aggregate-logs. This skill adds automatic friction detection and

a structured promotion path.

Friction Signal Types

| Signal | Detection Method | Weight |

|--------|-----------------|--------|

| Repeated corrections | User overrides same tool call 2+ times in session | High |

| Command failures | Exit code != 0 patterns (same command type fails repeatedly) | Medium |

| Permission denials | User denies tool call, indicating unexpected behavior | High |

| Re-reads | Same file read 3+ times in session (lost context) | Low |

| Retry loops | Same action attempted 3+ times with variations | Medium |

| User frustration | Explicit negative feedback or correction language | High |

Weight scoring: High = 3, Medium = 2, Low = 1 points

per occurrence. Weighted score determines graduation

velocity.

Three-Tier Storage Graduation

Tier 1: Friction Log (ephemeral, per-session)
  Location: ~/.claude/friction/sessions/{date}-{id}.json
  Retention: 30 days, then pruned
  Threshold: 1 occurrence, logged, no action

Tier 2: Pattern Candidate (persistent, LEARNINGS.md)
  Location: ~/.claude/skills/LEARNINGS.md (friction section)
  Threshold: 3+ occurrences across 2+ sessions
  Action: flagged for review in next friction report

Tier 3: Graduated Rule (CLAUDE.md or skill update)
  Threshold: reviewed + user-approved
  Action: permanent guidance added to project/user config
  Constraint: NEVER auto-modify CLAUDE.md

Graduation Formula

graduation_score = (weighted_count * recency_factor) / sessions_seen

recency_factor:
  last 7 days  = 1.0
  8-14 days    = 0.7
  15-30 days   = 0.4
  31+ days     = 0.1

Tier 2 threshold: graduation_score >= 6.0
Tier 3 proposal:  graduation_score >= 12.0

Detection Workflow

Run at session end, at 80% context usage (via

conserve:clear-context), or after failed improvement

cycles (when metacognitive-self-mod detects regression).

Step 1: Scan Session for Signals

For each friction indicator found, wrap it in the

shared session-capture envelope (ADR-0011) so

downstream readers can ingest friction signals and

trace-capture entries through one parser:

{
  "schema_version": "session-capture/1",
  "session_id": "2026-04-14-abc12345",
  "timestamp": "2026-04-14T10:23:00Z",
  "source": "friction-detector",
  "payload": {
    "signal_type": "retry_loop",
    "description": "rg command failed 3x, fell back to grep",
    "context": "searching for pattern in node_modules",
    "weight": "medium"
  }
}

Legacy files written before envelope adoption are read

as session-capture/0 (entire file treated as the

payload). See docs/adr/0011-session-capture-envelope.md

for the contract and migration path.

Step 2: Compare Against Existing Log

FRICTION_DIR=~/.claude/friction/sessions
mkdir -p "$FRICTION_DIR"

# Count prior occurrences of similar signals
if command -v rg &>/dev/null; then
  rg -c "$SIGNAL_TYPE" "$FRICTION_DIR"/*.json 2>/dev/null || echo "0"
else
  grep -rc "$SIGNAL_TYPE" "$FRICTION_DIR"/*.json 2>/dev/null || echo "0"
fi

Step 3: Calculate Graduation Score

Aggregate across session logs: sum weighted occurrences,

apply recency decay, divide by session count, compare

against tier thresholds.

Step 4: Propose Graduations

Tier 2 crossing: append to LEARNINGS.md friction section.

Tier 3 crossing: present proposal with evidence to user,

wait for explicit approval before any modification.

Step 5: Store Results

Write session log to

~/.claude/friction/sessions/{date}-{session_id}.json

and update ~/.claude/friction/index.json.

Anti-Noise Rules

Ignore these signals:

• One-off failures: transient network/CI errors

(unless they recur 3+ times)

• User-initiated exploration: deliberate

experimentation is not agent error

• Already-graduated patterns: covered by existing

CLAUDE.md rules or skill instructions

• External tool failures: MCP server crashes and

similar tool bugs unrelated to agent behavior

Decay factor: signals older than 30 days contribute

only 10% of their original weight (see graduation

formula recency_factor).

Friction Report Format

## Friction Report: Session {date}

### New Signals (Tier 1)
- [RETRY] `rg` command failed 3x, fell back to `grep`
- [RE-READ] Read SKILL.md 4 times (lost file structure context)

### Recurring Patterns (Tier 2 candidates)
- [CORRECTION] User corrected file path format 4x across 3 sessions
  Score: 8.4 (threshold: 6.0)
  Candidate: Add path format guidance to CLAUDE.md

### Graduation Proposals (Tier 3)
- [RULE] "Always use absolute paths in Read tool"
  Evidence: 7 corrections across 5 sessions
  Score: 14.2 (threshold: 12.0)
  Action: Approve / Reject / Defer

### Noise Filtered
- 2 transient network timeouts (ignored)
- 1 user-initiated deep exploration (ignored)

Integration

Feeds into: LEARNINGS.md (Tier 2 patterns, same

format as /abstract:aggregate-logs),

skill-improver (priority scoring), and

metacognitive-self-mod (pipeline effectiveness).

Consumes from: session transcripts,

aggregate_learnings_daily hook data, and the

performance tracker for trend correlation.

When NOT to Use

• Single isolated failures (wait for recurrence)
• Skill authoring (use abstract:skill-authoring)
• Routine log aggregation (use /abstract:aggregate-logs)

Related

• abstract:metacognitive-self-mod: improvement analysis
• abstract:skills-eval: evaluation criteria
• /abstract:aggregate-logs: manual LEARNINGS.md generation
• conserve:clear-context: triggers friction scan at 80%

Exit Criteria

• [ ] Session friction report produced in "Friction Report Format"

with at least one section (New Signals, Recurring Patterns,

or Graduation Proposals) populated

• [ ] Each signal written as JSON to

~/.claude/friction/sessions/{date}-{session_id}.json

via the session-capture/1 schema

• [ ] Patterns with graduation_score >= 12.0 generate a Tier 3

proposal; skill does not auto-modify CLAUDE.md

• [ ] Noise signals (network failures, user exploration) appear in

"Noise Filtered" and are excluded from graduation scoring