diff --git a/.claude/notes/automation.md b/.claude/notes/automation.md index fbd5c3f9..07262e8a 100644 --- a/.claude/notes/automation.md +++ b/.claude/notes/automation.md @@ -3,6 +3,26 @@ Lessons specific to Claude Code skills, slash commands, classifier interactions, and parallel-agent workflows in this repo. Newest-first. +### When a memory captures a recurring failure, ask whether a hook can enforce it + +A saved feedback memory ("do X before Y") is advisory: it relies on +the agent discovering and applying the rule at the right moment. A +pre-PR checklist memory landed mid-session was followed by a lint +failure shipped to CI within the hour — the memory was in place, +the failure mode it described still occurred. The same gap was then +closed reliably by a `PreToolUse` hook that injects the checklist as +a system reminder the agent cannot miss. + +Memory remains useful for *rationale* (six-months-cold-reader can +look up *why* the rule exists). Hooks provide *enforcement* (the +agent cannot proceed without acknowledgment). For any "always do X +before Y" pattern, prefer the hook; keep the memory as the +explanation for why the hook exists. + +Anchor: `.claude/settings.json` `PreToolUse.Bash` hook (PR #80 +commit `3c12d02`); related personal memory cites +`feedback_test_plan_before_pr`. + ### Match shell-command hooks by regex word-boundary, not substring Substring patterns like `*"gh pr create"*` fire on any command that diff --git a/.claude/notes/review-patterns.md b/.claude/notes/review-patterns.md index 481b77ec..37cecc25 100644 --- a/.claude/notes/review-patterns.md +++ b/.claude/notes/review-patterns.md @@ -4,6 +4,29 @@ Lessons about multi-lens review, adversarial passes, and iterative review prompt construction when running review tasks via the Agent tool. Newest-first. +### Self-rate work, then write criteria for the next grade up + +Before declaring your own work done, rate it (B+, A-, A) and write +the measurable criteria that would elevate it one letter grade. +Implement the criteria that fit within the current PR's bounded +scope; defer the rest to FOLLOWUPS. Re-rate. Repeat until the +marginal cost of the next jump exceeds the marginal value. + +The forcing function — "what specifically would elevate this?" — +is sharper than "anything else?" because it requires articulating +measurable criteria. PR #76 went B+ → A → A+ in two iterations +this way; each iteration closed real structural gaps (CI visibility +loop, falsifying test, graduated alert tier, helper extraction, +carve-outs, regex decomposition). + +Diminishing-returns inflection: A → A+ produces smaller deltas +than B+ → A. Pay the A+ cost when explicitly asked or when the +work is load-bearing enough to justify it; otherwise stop at A. + +Anchor: PR #76 commit `869450b` (final A+ state); the review- +iteration commits leading up to it are visible in +`git log origin/main..869450b`. + ### Spawn an explicit adversarial reviewer after graded reviewers converge "Find what others missed" produces a qualitatively different signal diff --git a/docs/notes/ci.md b/docs/notes/ci.md index 3be48dd7..ea5e23ea 100644 --- a/docs/notes/ci.md +++ b/docs/notes/ci.md @@ -4,6 +4,25 @@ Lessons specific to the local and remote continuous-integration surface. The `make ci` source-of-truth rule is in `AGENTS.md` under load-bearing lessons. Newest-first. +### Frame CI / perf projections as ranges, not single numbers + +A wall-time projection labeled "X seconds" invites a "is it really +that?" follow-up when actual diverges. Verify the projection's +assumptions empirically before publishing, or frame as a range +("expect 150–250s, bounded by Y") that absorbs variance the author +has not yet measured. + +PR #72's verify-split was projected at 155s wall time; actual was +242s — the projection assumed setup-go cache amortization that +does not happen across parallel jobs (verified post-merge in PR +#77). The cost of the unverified projection was an investigation +round to explain the gap. + +Anchor: PR #72 commit `7375cef` body (the 155s claim); PR #77 +`docs/FOLLOWUPS.md` § "CI wall-time (post-verify-split)" entry +that records the actual measurement and falsifies the cache +assumption. + ### Express CI rate-limited assertions in per-unit-of-work units CI assertions that divide a measurement by wallclock break under