70 lines
4.2 KiB
Markdown
70 lines
4.2 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.
|
|
- `[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.
|
|
- `[recurring]` When a **deferred** decision later resolves, docs that referenced the
|
|
deferral go stale and a plan's file-map can miss them (e.g. resolving the mesh-VPN
|
|
choice left `new-host.md` still saying "mesh VPN (choice deferred)"; the ubongo work
|
|
similarly left a contradiction in CLAUDE.md). A *broadened* final grep sweep caught
|
|
both. → On resolving a deferred decision, grep all canonical docs for the deferral
|
|
language ("choice deferred", "pending", "TBD", the placeholder's name) and reconcile
|
|
every hit — don't rely on the plan's file-map alone. Worth a `/review-repo` check for
|
|
lingering "deferred/pending/TBD" references whose ADR has since resolved.
|