boma/docs/FRICTION.md

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

## 2026-05-31

- I asked to draft an ADR and got: No formal status-header convention, but since this is a draft for discussion I'll mark it Proposed so it isn't mistaken for an
  accepted decision. Here's the draft.

## 2026-06-01

- `[friction]` The `finishing-a-development-branch` flow (and generic AI/dev tooling)
  offers "push and open a Pull Request," but our Forgejo `origin` is trunk-based with
  no merge-request / approval gate (CLAUDE.md git conventions). That option doesn't
  apply — the real path is local fast-forward merge to `main`, then push. → Skills and
  conventions that assume a GitHub-style PR workflow need a homelab-aware variant;
  encode that here "finishing a branch" means merge-locally-then-push, not open-a-PR.