2.8 KiB

Raw Permalink Blame History

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:

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

### 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)

### references/layout/skill-structure.md
**What happened:** Confusing
**Suggestion:** Make it better

Good operational friction notes

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

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

### 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.

2.8 KiB Raw Permalink Blame History