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 under Open signals — don't curate, don't fix there. 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), migrates durable knowledge into the right docs, and moves consumed signals into the decisions ledger below.

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.

---

Open signals

(append new raw signals here; the next kaizen review consumes them)

• [recurring] Execution-mode menu asked AGAIN despite the 2026-06-10 "mechanical fix" (2026-06-14): at the M1 (public_dns) plan handoff I presented the "1. Subagent-Driven / 2. Inline Execution — which approach?" menu and asked the user to pick. The decisions ledger (2026-06-10) records this exact behaviour as CHANGE → mechanical: "Stop hook in .claude/settings.json blocks the turn if the menu appears and tells me to proceed subagent-driven." It did not fire — either the hook is absent in this clone, its matcher doesn't match the wording the writing-plans skill actually produces, or it isn't installed/active. The standing agreement is to default straight to subagent-driven without asking. → verify the Stop hook exists and that its pattern matches the real menu text (the skill scripts "Two execution options" / "Which approach?"); if it relies on .claude/settings.json hooks that aren't active here, that's the gap. 5th occurrence (06-05/06/09/10/14).

• [friction] ADR-writing policy is unsettled (2026-05-31): drafting an ADR, I invented a Status header ("Proposed") on the fly because there's no documented convention for how we write ADRs (status lifecycle, required sections). → TODO 10.2 — decide a minimal ADR template / status convention.

• [recurring] Brainstorming's "user reviews spec" gate fires despite a standing agreement to skip it (2026-06-10): writing the ADR-structure spec, I stopped to ask the user to review the finished spec before writing the plan — the superpowers:brainstorming skill scripts that gate. We had previously agreed I should move directly from the Q/A to the implementation plan once the spec is written. Same shape as the execution-mode-menu signal: an external skill's script conflicting with a boma convention, where prose reminders don't hold. → consider a mechanical guard (Stop-hook family) or a CLAUDE.md/skill-override note that suppresses the spec-review gate.

• [recurring] Subagent faithfulness self-reports can be wrong — controller must diff (2026-06-10): during the ADR-023 retroactive restructure, an implementer subagent reported "0 substantive deletions, the See-also lines reappear verbatim" for ADR-014, but it had actually dropped the cross-reference lines. Caught only by the controller independently running git show <sha> | grep '^-[^-]'. For faithfulness-critical edits delegated to subagents, the agent's own audit is not sufficient evidence. → systematize a controller-side deletion-audit step (every - line must be a classified, expected change) before accepting any "presentational-only" restructure; consider a helper script.

---

Kaizen reviews — decisions ledger

Consumed signals and where their resolution now lives. Newest first.

2026-06-10

Signal (first seen)	Verdict	Resolution / where it lives now
Execution-mode menu asked at plan handoff — 4× (06-05/06/09/10)	CHANGE → mechanical	Stop hook in .claude/settings.json blocks the turn if the menu appears and tells me to proceed subagent-driven. Prose reminders (CLAUDE.md, memory, 3 FRICTION entries) had failed four times — the lesson is that a behaviour conflicting with an external skill's script needs a mechanical guard, not another note.
Every git commit needs rbw unlock — recurring (05-30)	CHANGE	Root cause was not the vault syntax-check (.ansible-lint already excludes vault.yml); it was ansible-lint auto-loading + decrypting inventories/production/group_vars/all/vault.yml via the wired vault_password_file. Scoped the pre-commit ansible-lint hook (always_run: false + files: ansible content) so docs-/config-only commits skip it and need no vault. Ansible-content commits still need rbw (intrinsic to linting vault-backed plays; accepted).
make test fails when run non-activated — ansible-config not found (06-06)	CHANGE	Makefile test/test-all now prepend $(CURDIR)/.venv/bin to PATH.
Molecule image missing from the Forgejo registry (06-06)	already built	make molecule-image-push target exists.
Deferred decision goes stale across docs — 3× (06-05)	already built	scripts/repo-scan.py open-deferred-item / stale-deferred checks, run by /review-repo.
make new-role brace-expansion fails under dash (05-30)	fixed	Explicit paths in the Makefile target.
nft iif vs iifname, Molecule ansible_host, apply-path coverage blind spot, render-nft -c pattern (06-06)	MIGRATE	→ docs/testing/gotchas.md (pointer from ADR-008).
hooks-need-restart, pre-commit stashes unstaged, rbw sync stale cache, zsh word-split (05-30)	MIGRATE	→ docs/runbooks/claude-code-setup.md "Environment gotchas".
finishing-a-development-branch offers open-a-PR vs our trunk-based merge (06-01)	accepted	Same root cause as the menu ask (external skill script vs boma convention). CLAUDE.md already mandates trunk-based merge-to-main; covered by the Stop-hook family + awareness. Revisit if it recurs.

Process note: the /retro tool (TODO 11) still isn't built, so this review was manual. Curating by hand (migrate durable knowledge → docs, archive consumed signals → this ledger) worked well; fold that curation step into /retro when it's built.