sjat
91713127cb
- New docs/testing/gotchas.md (nft iif/iifname, Molecule ansible_host, apply-path coverage blind spot, render-nft-c pattern); pointer from ADR-008. - claude-code-setup.md gains "Environment gotchas" (hooks-need-restart, pre-commit stashes unstaged, rbw sync cache, zsh word-split). - FRICTION.md restructured into Open signals + a decisions ledger; consumed signals archived with where their resolution now lives. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
51 lines
3.9 KiB
Markdown
51 lines
3.9 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 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)_
|
||
|
||
- `[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.
|
||
|
||
---
|
||
|
||
## 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.
|