docs: harvest review lessons from PRs reviewed 2026-07-31 to 2026-08-07

Draft
SA
3mo ago
+143-91

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:

PRWhat review surfaced
#10121ogenstad ×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
#10132cubic ×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
#10105ajtmccarty (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
#9805ajtmccarty: 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
#10113cubic (author-validated): grouping migrations into a "phase" is not serialization — InfrahubBatch runs everything concurrently
#10146/#10147ogenstad: 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
#10133cubic (author-validated): integration tests polling for async outcomes instead of fixed sleeps
#10137cubic + ogenstad's concession: logic that "needs the full integration fixture" was a pure function over constructible data all along
#10122cubic: a new Settings field reached the generated, CI-validated root compose file but not the hand-maintained development/ anchor nothing validates
#8594ogenstad (resolution landed this week): no REST endpoint to serve an SDK method — extend the existing GraphQL query; the SDK method was removed instead
#10153cubic: drill-down links still referencing an undefined $datasource variable after the query targets were fixed
#9953BeArchiTek: 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 under db.is_transaction; watch nested retried callers
  • dev/knowledge/backend/query-pattern.md — the two READ-pagination failure modes (insert_limit = False without own LIMIT; missing total-order ORDER BY)
  • dev/guides/backend/creating-migrations.md — fix data bugs in the migration layer, not runtime save paths; per-item try/collect into MigrationResult.errors; batch by the memory-bounding unit
  • dev/knowledge/backend/database-schema.md — kind property is concrete-only, generics are labels; type concrete-only query inputs as list[NodeSchema]
  • dev/knowledge/backend/events.md — changelog models mask secrets only at construction; assignment after construction leaks them
  • dev/knowledge/backend/async-tasks.md — InfrahubBatch is concurrent, not ordered
  • dev/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 unreachable
  • dev/guidelines/backend/checklist.md — Configuration section: the generated/hand-maintained compose split
  • backend/AGENTS.md — new REST endpoints join Ask First; creating-migrations.md routed in the Guides list (it was missing entirely — nothing ever loaded it)
  • .agents/commands/pre-ci.md — plain ruff check CI-parity step; corrected the claim that the invoke tasks report unfixable violations
  • development/grafana/AGENTS.md (new) — defined datasource variables only; sweep link surfaces; regenerate the standalone compose
  • docs/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.py orders edge selection without the documented r.status ASC tiebreaker — the convention is already written in query-pattern.md/database-schema.md; this is a latent code issue, not a doc gap
  • develop's Grafana dashboards still carry 42 undefined-$datasource references that #10153 fixed only on release-1.11 — watch the branch-sync for conflicts
  • changelog/models.py's own set_value_previous bypasses 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.md when it lands
  • the stable/develop ruff BLE divergence (#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