96 lines
2.8 KiB
Markdown
96 lines
2.8 KiB
Markdown
# 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.
|