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.

2026-06-05

• [recurring] The writing-plans skill ends by asking "subagent-driven vs inline execution?" — always answer subagent-driven here. Don't ask; default straight to subagent-driven (fresh subagent per task + review between tasks). → Standing preference; skip the execution-mode prompt.