docs: harvest review lessons from this week's PRs into internal docs
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'suseDialogsteals focus from a nesteddefaultOpencombobox 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:PopoverDialogwraps react-aria'suseDialog, whose focus-on-mount steals focus from a nesteddefaultOpencombobox/dropdown portal and closes it — documents the carve-out to use plainPopoverfor 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 inmerge-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 indatabase-schema.mdso 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