# FRICTION.md — kaizen friction log

Raw signals for the periodic **kaizen review** (the methodology retrospective; see
`docs/TODO.md`). This is the input that keeps our tooling and conventions sharpening
over time instead of only accreting.

**How to use:** append freely *during* work — don't curate, don't fix here. Capture
friction, surprises, fixes that keep recurring, and tooling that isn't earning its
keep. The kaizen review reads this, then proposes **add / change / remove** (biased
toward *remove*) and records the decisions as ADRs.

**Entry format:** `date — [tag] observation — (optional) → systematization idea`
Tags: `[friction]` recurring annoyance · `[gotcha]` surprising behaviour ·
`[recurring]` keeps coming back, should be systematized · `[unused]` tooling not
earning its keep.

---

## 2026-05-30 — initial seed (from the Claude-Code setup session)

- `[recurring]` Every `git commit` needs `rbw` unlocked (the pre-commit ansible-lint
  hook decrypts `vault.yml` for its syntax-check). Mitigated with a 5h lock timeout
  and an `rbw unlocked` pre-flight convention. → *Open:* could ansible-lint skip vault
  decryption for syntax-check, so committing doesn't need the vault at all?
- `[gotcha]` pre-commit stashes *unstaged* changes before running hooks, so a partial
  commit reverted an interdependent file (`ansible.cfg`) and failed. → Commit
  interdependent changes together, or stage the config change first.
- `[gotcha]` `make new-role` had never worked on this host: `mkdir {a,b,c}` brace
  expansion fails under `/bin/sh` (dash). Fixed with explicit paths. → A real run
  catches what static review can't; consider smoke-testing scaffold commands.
- `[gotcha]` `rbw sync` is required after adding a Vaultwarden item before `rbw get`
  finds it (stale local cache).
- `[gotcha]` This shell is zsh — unquoted `$VAR` does not word-split, so a variable
  holding a file list was passed as a single argument. → Use explicit args/arrays.
- `[friction]` Long sessions: I make a batch of edits but can't commit until you
  `rbw unlock`. The 5h timeout + pre-flight check address the symptom; watch whether
  it still bites.
- `[gotcha]` Hooks (or any new `.claude/settings.json`) added mid-session don't
  activate until a Claude Code **restart** — the settings watcher only tracks settings
  files that existed at session start. Opening `/hooks` and dismissing did *not* load
  them. → Fresh sessions load them normally; restart after adding hooks.