docs: harvest review lessons from PRs reviewed 2026-07-31 to 2026-08-07
Why
A /harvesting-review run over review activity 2026-07-31 → 2026-08-07. #10145 already harvested the window's merged PRs, so this run reads what it skipped: the week's open, draft, and closed-superseded PRs plus merges it postdates — where reviewers did much of their teaching this week, and where lessons otherwise die when the PR closes unmerged.
Stacked on #10145 → #10098 → #10030 → develop, so its unmerged doc edits are the dedup baseline and the stacks don't collide.
Non-goals: no code changes — latent code issues the investigation confirmed are flagged below as follow-up candidates, not fixed here.
Source PRs
29 PRs from the window were read (resolved and unresolved threads both); the 17 already covered by #10145/#10098 were excluded up front. PRs that produced lessons:
| PR | What review surfaced |
|---|---|
| #10121 | ogenstad ×2 + author self-review: @retry_db_transaction on the whole create mutation replays an already-committed transaction (duplicate node); a marker + type: ignore added to production code so a test could see it — reviewer supplied the ast-based wiring test instead |
| #10132 | cubic ×4 (author-validated): a READ query with insert_limit = False and no own LIMIT never finishes paging, plus the author's ORDER-BY-disjointness addition; one bad item aborting a multi-branch migration; batches sized by node count when edges bound memory; a delete assertion reading the wrong branch |
| #10105 | ajtmccarty (changes requested): fix the schema-migration layer, don't lazily repair in save() — the PR was closed for #10113. cubic: post-construction changelog assignment bypasses the Password masking validator |
| #9805 | ajtmccarty: a Cypher filter on n.kind silently matches zero generics — generics exist only as labels; the fix typed the query input as list[NodeSchema] so misuse fails in CI |
| #10113 | cubic (author-validated): grouping migrations into a "phase" is not serialization — InfrahubBatch runs everything concurrently |
| #10146/#10147 | ogenstad: no changelog fragment for a change that touches no source code. Author root-cause: invoke lint tasks run ruff check --diff, blind to unfixable violations CI catches |
| #10133 | cubic (author-validated): integration tests polling for async outcomes instead of fixed sleeps |
| #10137 | cubic + ogenstad's concession: logic that "needs the full integration fixture" was a pure function over constructible data all along |
| #10122 | cubic: a new Settings field reached the generated, CI-validated root compose file but not the hand-maintained development/ anchor nothing validates |
| #8594 | ogenstad (resolution landed this week): no REST endpoint to serve an SDK method — extend the existing GraphQL query; the SDK method was removed instead |
| #10153 | cubic: drill-down links still referencing an undefined $datasource variable after the query targets were fixed |
| #9953 | BeArchiTek: opaque-white Excalidraw exports confirmed as the 9-of-16 majority convention in docs/docs/media/ (verified here) |
Read with nothing durable to harvest: #10141, #10154, #10149, #10144, #10099, #10124, #10080, #10089, #10081, #7569, #9631/#9635/#8902/#10148/#10101/#10142/#10153-approvals (activity pre-window, bare approvals, or bot no-issue reviews).
What changed
New rules/knowledge (each verified against the code before writing — the retry semantics against database/__init__.py/create.py/mutations/main.py, the paging loop against core/query/__init__.py, the masking validator against changelog/models.py, the label model against core/node/__init__.py, the compose asymmetry against tasks/release.py + ci.yml, the dashboards against the JSON on develop):
dev/knowledge/backend/mutations.md— Transaction Retry: wrap only rollback-able scopes, never post-commit reads; skip underdb.is_transaction; watch nested retried callersdev/knowledge/backend/query-pattern.md— the two READ-pagination failure modes (insert_limit = Falsewithout own LIMIT; missing total-orderORDER BY)dev/guides/backend/creating-migrations.md— fix data bugs in the migration layer, not runtime save paths; per-item try/collect intoMigrationResult.errors; batch by the memory-bounding unitdev/knowledge/backend/database-schema.md—kindproperty is concrete-only, generics are labels; type concrete-only query inputs aslist[NodeSchema]dev/knowledge/backend/events.md— changelog models mask secrets only at construction; assignment after construction leaks themdev/knowledge/backend/async-tasks.md—InfrahubBatchis concurrent, not ordereddev/guidelines/backend/testing.md+.agents/rules/testing-python.md— wiring tests parse source (ast+inspect) instead of instrumenting production code; poll-don't-sleep for async effects; branch-attributable removal assertions; extract-a-pure-function before claiming the cheap tier is unreachabledev/guidelines/backend/checklist.md— Configuration section: the generated/hand-maintained compose splitbackend/AGENTS.md— new REST endpoints join Ask First;creating-migrations.mdrouted in the Guides list (it was missing entirely — nothing ever loaded it).agents/commands/pre-ci.md— plainruff checkCI-parity step; corrected the claim that the invoke tasks report unfixable violationsdevelopment/grafana/AGENTS.md(new) — defined datasource variables only; sweep link surfaces; regenerate the standalone composedocs/AGENTS.md— opaque-white Excalidraw exports
Strengthened where it already lived (rule existed, author still tripped): the creating-changelog-entries skill said "no fragment for changes with no user-facing effect" three lines below a parenthetical pushing "(most internal maintenance still gets a housekeeping fragment)" — the author of #10146 cited exactly that reflex. The parenthetical now defers to the boundary, and lint/typing config cleanups are a named example.
Paid for by: compressing testing.md's nested-dataclass example and query-pattern.md's duplicated accessor/return-properties sections. Net +143/−91; testing.md 389 and query-pattern.md 430 (was 459 — still over its 200–400 range; the ## Internals split remains its own change, as #10145 noted).
Not codified, flagged as follow-ups (investigation confirmed them real in code):
migrations/query/attribute_add.pyorders edge selection without the documentedr.status ASCtiebreaker — the convention is already written inquery-pattern.md/database-schema.md; this is a latent code issue, not a doc gap- develop's Grafana dashboards still carry 42 undefined-
$datasourcereferences that #10153 fixed only onrelease-1.11— watch the branch-sync for conflicts changelog/models.py's ownset_value_previousbypasses the masking validator (same mechanism as the documented gotcha)- #10133's broker-side-durability lessons are solid but the Redis driver is an unmerged draft — harvest into
message-bus.mdwhen it lands - the
stable/developruffBLEdivergence (#10146/#10132) makes release-branch merges lint-red on develop; the team intends to reconcile the config rather than document it
How to review
Every lesson cites its source PR above; the highest-leverage edits are mutations.md (Transaction Retry) and the query-pattern.md pagination block, both bugs-in-waiting rather than style. Bot-sourced lessons were held to the skill's lower-confidence bar: kept only where the author landed the fix or the claim was re-verified against the code here.
How to test
uv run invoke docs.lint
Docs-only. CI's markdown-lint and Vale cover docs/**; relative links and anchors in the edited dev/ files checked locally (#return-labels target exists; lychee's dev/**/*.md glob covers the edited files).
Impact & rollout
- Backward compatibility: docs-only, no runtime impact
- Deployment notes: safe to merge once the stack below it lands
Checklist
- Tests added/updated (n/a — docs-only)
- Changelog entry added (n/a — internal docs, no user-facing effect)
- 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_01LYisRTn3sPygP55cxbVqzG
Generated by Claude Code