sjat
11af84938d
docs/FRICTION.md: a running log of friction/gotchas/recurring-fixes/unused tooling, seeded with this session's real signals — raw material for the periodic kaizen review. docs/TODO.md: schedule building /retro in ~1 week, and record the Claude-setup decision. (Also carries your earlier backlog edits.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
37 lines
2.1 KiB
Markdown
37 lines
2.1 KiB
Markdown
# 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.
|