From 778c042dd9d5364a31ff3c6870d5577324817ba2 Mon Sep 17 00:00:00 2001 From: Tri Lam Date: Fri, 15 May 2026 05:51:01 -0700 Subject: [PATCH] [docs] Capture session lessons into pr-workflow / memory-rules / conftest notes Four lessons surfaced during the M5b chart work that are durable enough to outlive the session. Each lands in a new topic note with an anchor the next contributor can grep for to catch regression: - pr-workflow: update the PR body each review round (not just at open), because the squash-merge body is what becomes permanent on main; iterative reviews need each round's prompt to enumerate prior-round artifacts so the next pass surfaces residual gaps rather than re-reporting closed findings. - memory-rules: when a memory rule tightens and collides with an existing constraint (e.g. AI-trailer cleanup vs. no-history-rewrites on already-pushed commits), name forward-only compliance as the resolution in the offending file so the next contributor does not relitigate. - conftest: rego deny rules that reference `pod_spec.` fire on non-pod documents (ConfigMap, ServiceAccount, Secret) unless guarded with `input.spec.template.spec`, because rego's undefined-propagation rules make `not pod_spec.x == true` evaluate true when pod_spec is absent. AGENTS.md topic index gains three pointers (one per new note). Skill format check clean: no banned vocabulary, no AI attribution, anchors present on every entry, AGENTS.md at 36 lines (cap 150). Signed-off-by: Tri Lam --- AGENTS.md | 3 +++ docs/notes/conftest.md | 19 +++++++++++++++++++ docs/notes/memory-rules.md | 20 ++++++++++++++++++++ docs/notes/pr-workflow.md | 29 +++++++++++++++++++++++++++++ 4 files changed, 71 insertions(+) create mode 100644 docs/notes/conftest.md create mode 100644 docs/notes/memory-rules.md create mode 100644 docs/notes/pr-workflow.md diff --git a/AGENTS.md b/AGENTS.md index a92ecc51..f213ef02 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,9 @@ area. Format conventions: `docs/notes/README.md`. - [CI](docs/notes/ci.md) — what `make check` and `make ci` each cover, and which gates have caught real regressions. - [Reviews](docs/notes/reviews.md) — when and how to run multi-lens reviews, and how to triage uplift items between PR-scope and follow-ups. +- [PR workflow](docs/notes/pr-workflow.md) — body-sync, iterative-review prompt discipline. +- [Memory rules](docs/notes/memory-rules.md) — reconciling rule collisions with forward-only compliance. +- [Conftest / OPA rego](docs/notes/conftest.md) — pod-spec guards and non-pod-document evaluation traps. diff --git a/docs/notes/conftest.md b/docs/notes/conftest.md new file mode 100644 index 00000000..e87e4fa2 --- /dev/null +++ b/docs/notes/conftest.md @@ -0,0 +1,19 @@ +# Conftest / OPA rego + +Lessons specific to the rego policies that gate the Helm chart at +`install/kubernetes/tracecore/policies/conftest/`. Format conventions: +`docs/notes/README.md`. + +### Guard rego deny rules with `input.spec.template.spec` + +Rego rules that reference `pod_spec.` are silently undefined +when the input is a non-pod document (ConfigMap, ServiceAccount, +Secret). But `not pod_spec. == true` evaluates to `true` when +`pod_spec` is undefined, so policies meant to police pods fire on +every ConfigMap in the rendered chart. Every deny rule that touches +the pod spec must start with `input.spec.template.spec` to anchor +evaluation. + +Anchor: `install/kubernetes/tracecore/policies/conftest/tracecore.rego` — +every `deny contains msg if { ... }` block that references +`pod_spec` or `all_containers`. diff --git a/docs/notes/memory-rules.md b/docs/notes/memory-rules.md new file mode 100644 index 00000000..1f703601 --- /dev/null +++ b/docs/notes/memory-rules.md @@ -0,0 +1,20 @@ +# Memory rules + +Lessons about authoring and reconciling the durable memory in +`/Users/tree/.claude/projects/-Users-tree-Desktop-tracecore/memory/`. +Format conventions: `docs/notes/README.md`. + +### Reconcile colliding memory rules with a governance call, not cleanup + +When a memory rule tightens and collides with an existing constraint +(canonical example: a "no AI attribution" tightening that would +require rewriting already-pushed commits, blocked by "no history +rewrites"), naming the resolution as forward-only-compliance prevents +the next contributor from relitigating. Record the disposition in the +colliding memory file itself so it surfaces on the next look-up. + +Anchor: any memory file under +`$HOME/.claude/projects/-Users-tree-Desktop-tracecore/memory/` +that introduces a constraint stricter than the one it replaces — grep +for `Updated 20` headers and verify the "How to apply" section +addresses prior-state work. diff --git a/docs/notes/pr-workflow.md b/docs/notes/pr-workflow.md new file mode 100644 index 00000000..afbfe2b6 --- /dev/null +++ b/docs/notes/pr-workflow.md @@ -0,0 +1,29 @@ +# PR workflow + +Repo-resident lessons on opening, iterating on, and merging PRs in +this codebase. Format conventions: `docs/notes/README.md`. + +### Update the PR body each review round, not just at open + +When a PR goes through multiple rounds of review-driven fixes, the +description authored at PR-open often understates what actually +shipped: new files, new rules, new knobs added in later commits. On +squash-merge, the body becomes the permanent commit message on +`main` — a stale body turns into a permanent under-statement of +scope. CHANGELOG entries can mitigate this, but the commit body is +what `git log` shows by default. + +Anchor: `git log origin/main -1 --format=%B` after every squash-merge +of an iterative PR; compare against the diff to catch drift. + +### Pre-load prior-round findings when running an iterative review + +Review prompts that do not enumerate what already shipped in earlier +rounds re-surface those exact findings as "new." The delta-quality +output of an iterative review depends on each round explicitly listing +the artifacts (rules, fixtures, knobs, doc sections) that landed +previously, so reviewers focus on the residual gap. + +Anchor: the prompt body of any Agent tool call dispatching an +iterative review must include an explicit "what already shipped" +block; without it, the review repeats itself.