# Friction Reflection

How to identify and record friction at the end of a task.

## What is friction?

Friction is anything that made the task harder than it should have been.

### Documentation friction
Knowledge docs didn't serve you well:
- Information was missing
- Information was hard to find
- Information was unclear or ambiguous
- You made a mistake because docs were misleading

### Operational friction
Process or architecture caused unnecessary work:
- **Navigation friction**: Too many index files read to reach knowledge (tree too deep)
- **Context friction**: Work in main thread that cluttered context (should've been subagent)
- **Automation friction**: Deterministic subtask that would be faster/reliable as script

## The reflection prompt

At the end of every workflow, ask yourself:

> "Did I encounter friction during this task?"

Consider both documentation friction (docs missing, unclear, hard to find) and operational friction (too many hops, context clutter, scripting opportunities).

**If no:** Proceed to report. No action needed.

**If yes:** Record it in the task document under `## Friction / Improvement Notes`

## What to record

For each friction point, write:

```markdown
## Friction / Improvement Notes

### [target-file-path or process-name]
**Type:** Documentation | Navigation | Context | Automation
**What happened:** Brief description of the friction
**Suggestion:** What would have helped
```

## Examples

### Good friction note
```markdown
### references/layout/skill-structure.md
**What happened:** Didn't explain where project-level skills live vs plugin skills
**Suggestion:** Add a "Where skills live" section with both paths
```

### Bad friction note (too vague)
```markdown
### references/layout/skill-structure.md
**What happened:** Confusing
**Suggestion:** Make it better
```

### Good operational friction notes

```markdown
### Navigation
**Type:** Navigation
**What happened:** Read 4 index files before reaching the actual content I needed
**Suggestion:** Add direct link from CLAUDE.md or flatten the tree
```

```markdown
### Subagent opportunity
**Type:** Context
**What happened:** Ran 15-step verification in main thread, cluttered context
**Suggestion:** Document this as a subagent workflow or script
```

```markdown
### Script opportunity
**Type:** Automation
**What happened:** Manually checked 8 files for the same pattern
**Suggestion:** Create a lint script that checks this automatically
```

## When NOT to record friction

- One-time mistakes that won't recur
- Friction caused by user's unclear requirements (not a docs problem)
- Issues you already fixed in this task
- Extremely minor issues (typos, formatting)

## The goal

Build a trail of actionable improvements that the improvement workflow can harvest later. Quality over quantity.