docs: harvest review lessons from this week's PRs into internal docs

Merged
SA
4mo ago
+15-2

Why

Reviewers repeatedly had to spell out the same conventions on this week's PRs, because each lesson lived in a review thread and died there. This is a harvesting-review run over PRs merged 2026-07-21 → 2026-07-24 (the window since the last such run, #9991), turning the feedback that generalizes into durable internal-doc conventions so a future author (human or agent) follows the convention the first time.

Each candidate lesson was reconstructed against the before/after code, verified against the current codebase, and checked against what's already documented before landing — per .claude/skills/harvesting-review/.

Source PRs

Ten PRs were audited (research delegated to one subagent per PR); the ones that yielded a durable lesson:

  • #9948 (bilalabbad, column-header sort & filter menu) — pa-lem: PopoverDialog's useDialog steals focus from a nested defaultOpen combobox and closes it; bilalabbad: sort change without pagination reset causes a page-stitching bug on large datasets (fix deferred to a follow-up PR).
  • #10028 (polmichel, regeneration safe-fallback escalation) — cubic-dev-ai: a spec doc's scenario table cited test functions that don't exist anywhere in the repo yet.
  • #9996 (ajtmccarty, memory-efficient rollback query) — cubic-dev-ai: cleanup driven by ids collected in an earlier phase is lost if the process crashes between phases; the fix is already documented for the merge-recovery domain but not surfaced in the general migrations guide.
  • #9994 (ajtmccarty, node-scoped uniqueness constraint queries) — polmichel: UUID/liveness-check queries need an explicit test for the duplicate-UUID-from-migration case; the invariant is documented but the testing guide never points authors at it.

Also scanned with no new lessons to harvest (already covered, PR-local, in-flight elsewhere, universal hygiene, or no substantive review): #10027, #10025, #9990, #9791, #9995, #10000.

Not duplicated: #10000 surfaced several real lessons (N+1/set-based Cypher writes, exception-hierarchy verification before narrowing, an unreleased-feature changelog carve-out, ticket IDs in internal docs, dynamic Cypher labels) — all of these are already being fixed in the open PR #10005 (dev/guidelines/git-workflow.md, checklist.md, python.md, changelog.md, documentation.md, the neo4j-cypher-guide skill). Left alone rather than duplicated or conflicted, matching how #9991 excluded lessons already in-flight on other open PRs.

What changed

New rules:

  • dev/knowledge/frontend/design-system.md: PopoverDialog wraps react-aria's useDialog, whose focus-on-mount steals focus from a nested defaultOpen combobox/dropdown portal and closes it — documents the carve-out to use plain Popover for that content instead.
  • dev/guidelines/frontend/page-architecture.md: a new rule that an offset-paginated list with user-driven sorting must reset to page 1 on sort change, plus an anti-pattern table entry citing the PR.
  • dev/guidelines/documentation.md: before citing a specific test as verifying a scenario in a spec/status doc, confirm that test exists — label unwritten coverage as planned/unverified instead.

Strengthened existing coverage (rule existed but wasn't landing — "not discoverable" per the harvesting-review diagnosis):

  • dev/guides/backend/creating-migrations.md: cross-links the candidate-ids-across-phases pitfall already written up in merge-failure-recovery.md — the general migration guide never pointed authors at it.
  • dev/knowledge/backend/testing.md: cross-links the duplicate-UUID invariant already documented in database-schema.md so test authors are prompted to cover it instead of relying on a reviewer to ask.

Docs-only — no code, no generated files, no schema.

How to review

None of the five edits are .agents/rules/* (no per-turn token cost added) — all land in dev/guidelines/ or dev/knowledge/, loaded only via each area's router. The two "strengthen" edits are single-sentence cross-links to existing content, not new rules.

How to test

npx -y markdownlint-cli2 dev/guidelines/documentation.md dev/guidelines/frontend/page-architecture.md dev/guides/backend/creating-migrations.md dev/knowledge/backend/testing.md dev/knowledge/frontend/design-system.md

0 issues.

Impact & rollout

  • Backward compatibility: docs-only, no runtime impact
  • Deployment notes: safe to merge

Checklist

  • Tests added/updated (n/a — docs-only)
  • Changelog entry added (n/a — internal docs)
  • External docs updated (n/a)
  • Internal .md docs updated (internal knowledge and AI code tools knowledge)
  • I have reviewed AI generated content

🤖 Generated with Claude Code

https://claude.ai/code/session_01USfYPX72WZAoSeRjKHiUDR


Generated by Claude Code