docs: harvest review lessons from PRs reviewed 2026-08-21 to 2026-08-28

[saltas888]

Why

Reviewers repeated the same findings across this week's PRs — branch-targeting questions came up on five PRs (including ~18 bot notes on one PR citing a "release-vehicle policy" the repo's own guideline contradicts), "prove the regression test bites" was the resolution on four, and maintainers rejected housekeeping changelog fragments three times against what the root AGENTS.md line said. This is the weekly harvest run: it mines the week's review threads for rules that generalize, verifies each against the code, and routes the durable ones into the internal-doc layer.

Non-goals: no production code or test changes; no duplication of the changelog-content rule pending in #10400 (.agents/rules/changelog-entries.md) — the week's four human comments on changelog wording are deliberately left to that PR.

PRs I learned from

Lessons in this PR trace to review threads on:

• test(component): share read-only fixture datasets at class scope #10362, perf(core): create default account permissions concurrently (local-dev win, CI-neutral) #10364, chore(frontend): consolidate on Biome and drop oxlint/oxfmt [#10390] #10399, fix: scope branch-merge and proposed-change-review events to the default branch (closes #9761) #10422, perf(ci): upgrade mypy to 2.3.1 and run python-lint on arm64 #10432, docs: capture the context gaps found retrospecting the dark theme work #10391, chore(agents): make pre-ci detect changed areas and close the frontend gap #10405 (branch-targeting week) — fatih-acar asked "can we target stable?" twice for perf/test-reliability changes; polmichel routed a behavior-changing fix to develop with a release-note flag; saltas888 defended a develop base for wide reformatting on divergence-cost grounds against repeated bot notes → the git-workflow Branch Strategy section now states all three cases
• chore: stop the pre-ci frontend checks from leaking the working directory #10385, test: key the Prefect task manager setup memo on the server #10403, perf(ci): upgrade mypy to 2.3.1 and run python-lint on arm64 #10432 (housekeeping-fragment rejections) — the root AGENTS.md line said "internal maintenance still gets a housekeeping fragment" while maintainers waived or deleted exactly those fragments; the line now defers to the creating-changelog-entries skill's "not a catch-all / only when a user could notice" boundary
• feat(ci): E2E proof runs for the bug pipeline [IFC-3059] #10431, [scratch — do not merge] proof-run workflow replay (IFC-3059 quickstart) #10429 (spec-decision drift) — ~12 threads flagged spec/plan/quickstart/tasks files still describing a reversed storage decision; the existing AGENTS.md spec-drift rule covered changed figures but not reversed decisions, so it now names both
• perf(backend): stop re-reading object templates and the peers a create holds #10413, retire agnostic fields during branch delete #10384 (enum vs string literal) — "should use the enum" plus a hardcoded "DELETING"; the existing enum section covered typing but not the comparison side
• Add the Python transform target deriver #10416 — polmichel drew the union-of-small-dataclasses shape to replace a struct of mode flags whose combinations were mostly invalid; new python.md rule
• perf(backend): stop re-reading relationship peers during creates and updates #10404 — node.get_relationship(name) over getattr(node, name), asked twice and then swept across three modules; added to the existing getattr section
• perf(backend): stop re-reading object templates and the peers a create holds #10413, perf(backend): hand a template component the peer it carries #10426, fix(preferences): expose the inherited layer to fix the date preview #10424, perf(backend): read an object template a level at a time #10423 (regression guards that assert nothing) — three different humans resolved threads by running the test against the pre-fix code; new testing-python.md rule, plus the xfail-swallows-assertions trap
• test(backend): keep prefect test servers off kernel-ephemeral ports #10363 — an unrestored monkey-patch of a third-party class attribute; class attributes added to the existing save/restore enumeration
• feat(regeneration): narrow relationship-reached changes to owning members (IFC-2946) #10262 — "a dataclass should not be calling a component", asked twice with the injected-class shape drawn by the reviewer; one sentence added to the component-design rule
• perf(core): create default account permissions concurrently (local-dev win, CI-neutral) #10364 — start_session() builds a session straight from the driver, so writes escape any caller transaction (verified in database/__init__.py; the PR found permission writes surviving a rollback); recorded next to the transaction-retry knowledge
• docs: state what starts an artifact and Generator run #10437 — docs referenced a "Regenerate" button that doesn't exist; UI button/label text added to the docs verify-claims enumeration
• fix(frontend): confirm a branch is gone before redirecting to the default branch #10394 — pa-lem's wedge-the-app finding: under the app-wide retry: false REST client, an effect whose dependencies are all stable after a failure never retries; new react.md section with a router-entry load-trigger

Also read, with nothing durable to harvest (no in-window substantive threads, lessons already codified, PR-local design calls, or lessons owned by an open PR): #10439, #10440, #10438, #10396, #10434, #10416's remaining threads, #10435, #9807, #10405's pre-ci threads (fixed in that PR), #10424, #10427, #10431/#10429's workflow-security findings (PR-local, PoC drafts), #10231, #10246, #10262's remaining threads, #10421 (its findings were fixed in-PR), #10412, #10030, #10220, #10411, #10365, #10374, #10408, #10398, #10377, #10315, #10397, #10406, #10409, #10407, #10403, #10372, #10360, #10284, #10376, #10380, #10400, #10393, #10387, #10379, #10382, #10339, #10381, #10358, #10383, #10368, #10354, #10375, #10361, #10371, #10370, #10334 (docs accuracy pass owned by that open PR), #10359, #10367, #10348, #10362, #10422, #10423, #10426, and the bot merge/dependabot PRs in the window.

Notable non-edits, recorded deliberately:

• Changelog fragment content (gmazoyer on perf(backend): stop re-reading object templates and the peers a create holds #10413/perf(backend): hand a template component the peer it carries #10426, ajtmccarty on Fix branch scoping that made per-node automations fire twice #10374/fix(backend): apply INFRAHUB_TRACE_INSECURE and support TLS collectors #10398): open PR docs: add agent rule for changelog fragment content #10400 already adds .agents/rules/changelog-entries.md covering exactly this — no duplicate here.
• The temporal from <= $at edge-closure guard is contested: gmazoyer added it on fix: let an SSO user sign in after their account is deleted (closes #10304) #10435, ajtmccarty rebutted it as impossible for a migration running at the current timestamp on database migration for agnostic fields on deleted aware objects #10438. Not codified; worth watching.
• The TRY400 traceback-vs-task-log debate (ogenstad on chore(backend): enforce ruff TRY400 so error logs carry tracebacks #10220) is a genuine open design question about error-logging audiences, not yet a rule.
• code-doc-style is landing: ~15 threads this week were the bot enforcing it and authors complying — coverage that works, no edit needed.

What changed

Documentation layer only, 10 files, +49/−44 — the deletions paid for the additions:

• dev/guidelines/git-workflow.md (145→150, range 100–400): Branch Strategy reworked — perf/test-reliability changes join bug fixes on the oldest maintained branch; behavior-changing fixes wait for the minor with a release-note flag; wide mechanical churn lands where files diverge least; the tooling bullet's boundary corrected from "no source-code changes" to "no runtime source changes (…, test-only)"
• AGENTS.md: the two Always-Do line edits above (housekeeping boundary; reversed decisions)
• dev/guidelines/backend/python.md (464→462, over its 400 cap but net −2): three rules added, paid for by compressing the version-features tail (minimum supported is 3.10, so the 3.9/3.10 table rows were dead weight)
• .agents/rules/testing-python.md (82→86): regression-guard-must-bite section; class attributes in the save/restore list
• .agents/rules/backend-component-design.md (129, +1 sentence): the dataclass boundary
• dev/knowledge/backend/database-schema.md (397→391, back inside its 200–400 range): session-escapes-transaction paragraph; retry table compressed to a sentence
• docs/AGENTS.md, dev/knowledge/frontend/react.md + frontend/app/AGENTS.md router entry, dev/guides/frontend/writing-e2e-tests.md (rot sweep: issue ID in a skip-reason example, forbidden by code-doc-style)

What stayed the same: no production code, no tests, no user-facing docs pages, no schema changes.

How to review

Every edit cites its review threads in the commit message. The judgement calls worth a second pair of eyes: the git-workflow bullets encode fatih-acar's two "target stable?" asks and saltas888's divergence argument on #10399 — flag it if the release-vehicle policy reads differently; and the AGENTS.md housekeeping line now defers to the skill's narrower boundary, encoding this week's three maintainer rejections over the older, broader wording.

How to test

cd docs && npm install && cd .. && uv run invoke docs.lint

The lint's globs cover docs/docs/** only — this diff touches no files there (AGENTS.md files are excluded by the repo's markdownlint config), so it passes trivially; ran markdownlint-cli2 locally, 0 errors.

Impact & rollout

• Backward compatibility: documentation only; no behavior change.

Checklist

• Tests added/updated — N/A, docs only
• Changelog entry added — N/A, internal docs only (the boundary this PR codifies)
• External docs updated — N/A, no user-facing change
• 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_019BZYhKMNyKnTxvwJZpXbEC

---

Generated by Claude Code

[cubic-dev-ai]

All reported issues were addressed across 10 files

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Docs-only harvest PR: all 10 diffs update developer guidelines, AGENTS.md files, and knowledge docs to codify review lessons. No production code, tests, schema, config, or behavior change -- only descriptive/documentation text.

Re-trigger cubic</sub>