Skip to content

[docs] session retrospective: three meta-lessons captured#84

Merged
trilamsr merged 1 commit into
mainfrom
docs/session-retrospective-three-lessons
May 19, 2026
Merged

[docs] session retrospective: three meta-lessons captured#84
trilamsr merged 1 commit into
mainfrom
docs/session-retrospective-three-lessons

Conversation

@trilamsr

Copy link
Copy Markdown
Contributor

Summary

Three observations from the recent session that didn't fit the structured surfaces (already used for the load-bearing AGENTS.md entries in PR #81 and the agent-internal notes in PR #82). Each captured via the learn-from-mistakes flow and lands in its existing topic note.

.claude/notes/automation.mdMemory captures rationale; hooks enforce. The pre-PR checklist personal memory landed mid-session was followed by a lint failure shipped to CI within the hour. The same gap closed reliably by the PreToolUse hook installed shortly after. For any "always do X before Y" pattern, prefer the hook; the memory documents why the hook exists.

docs/notes/ci.mdFrame CI / perf projections as ranges, not single numbers. PR #72's 155s wall-time projection vs 242s actual cost an investigation round (later landed in PR #77) because the projection's setup-go-cache amortization assumption was unverified. Either verify assumptions empirically before publishing the number, or frame as a range.

.claude/notes/review-patterns.mdSelf-rate work, then write criteria for the next grade up. Forces articulation of measurable improvements rather than free-form "anything else?". PR #76's B+ → A → A+ came from two iterations of this exact pattern; each iteration closed real structural gaps.

A fourth lesson — "fix existing tools before proposing new ones" — was captured to personal memory (no PR, lives in ~/.claude/projects/.../memory/), not the repo, because it's a judgment heuristic about my own decision-making rather than a repo-resident convention.

Test plan

  • make doc-check clean (banned-phrase lint, link resolution, all gates).
  • learn-from-mistakes format check: banned vocabulary absent, no first-person AI phrasing, no AI attribution, all three entries carry Anchor: lines pointing at concrete PRs.
  • CI on this PR exercises doc-check + pr-lint.

Rollback

Each entry is a self-contained ### title + body + Anchor: block at the top of its file. No dependents elsewhere; reverting is a single Edit per file.

NONE — documentation only. Three meta-lessons from a recent session retrospective land in their existing topic notes (`automation.md`, `ci.md`, `review-patterns.md`). No runtime behavior change.

Three observations from the recent session that aren't already
in the structured surfaces, captured via the learn-from-mistakes
flow. Each lands in its existing topic note.

automation.md — memory captures rationale; hooks enforce. The
pre-PR checklist memory landed earlier was followed by a lint
failure shipped to CI within the hour. Same gap closed reliably
by the PreToolUse hook installed soon after. For 'always do X
before Y' patterns, prefer the hook; the memory documents why.

ci.md — frame CI/perf projections as ranges, not single numbers.
PR #72's 155s wall-time projection vs 242s actual cost an
investigation round because the projection's setup-go-cache
amortization assumption was unverified. Either verify assumptions
empirically before publishing the number or frame as a range.

review-patterns.md — self-rate work, then write criteria for the
next grade up. Forces articulation of measurable improvements
rather than free-form 'anything else?'. PR #76's B+ → A → A+
came from two iterations of this pattern.

make doc-check clean locally.

Signed-off-by: Tri Lam <trilamsr@gmail.com>
@trilamsr trilamsr enabled auto-merge (squash) May 19, 2026 08:41
@trilamsr trilamsr merged commit caa1011 into main May 19, 2026
8 checks passed
@trilamsr trilamsr deleted the docs/session-retrospective-three-lessons branch May 19, 2026 08:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant