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

Closed
SA
3mo ago
+56-92

Why

A /harvesting-review run over the PRs reviewed 2026-07-31 → 2026-08-06, the window since the previous run (#10098, which covered 2026-07-24 → 2026-07-31). Reviewers kept spending their time on the same things; each lesson lived in a thread and died there.

Stacked on #10098 → #10030 → develop. This run depends on both: it strengthens a rule #10098 added and follows the size discipline #10030 introduced.

The headline is that three of the eight lessons were already documented and a reviewer still had to raise them. Those are strengthened where they already live — no duplicate rules.

Source PRs

Fifteen merged PRs read, resolved and unresolved threads both, across develop and release-1.11. Dependabot bumps and branch-sync merges skipped.

PRWhat review surfaced
#10055ajtmccarty ×3: a component building its collaborator mid-run; wiring errors raised at runtime instead of construction. cubic: a cascade source accepted with no output capturer; both sides of the contract erased to Any
#10058ajtmccarty: inject SchemaManager instead of reaching for registry; a predicate living on the model
#10095ajtmccarty: parametrize over dict keys with an in-test lookup; task logic that should live in a module, which would also retire its deferred imports; a closed value set typed as str
#10106gmazoyer ×2: a Query subclass keeping its own limit/offset; get_as_list_of_type existing and being missed
#10096gmazoyer: spec vocabulary in a test name that means nothing without the spec
#10108ajtmccarty: an absolute performance figure in an ADR. cubic: an ADR claim the code contradicts
#10111saltas888: URL state mirrored into a Jotai atom. cubic: a toast assertion that passes with the wrong branch name
#10128saltas888: is a useMemo still needed under the React Compiler? cubic: an isFetching flag the provider never reads, making its test inert
#10129cubic ×3: "main" → is_default behavior changes with no test exercising a non-main default
#10114ajtmccarty ×3: doc claims about merged-branch behavior the code contradicts
#10090, #10104bot findings retracted after a human corrected them
#10123, #10125, #10136scanned, no durable lesson

#10079 and #10002 also merged in this window but were already harvested into #10030.

Strengthened — the rule existed and was missed anyway

.agents/rules/backend-component-design.md — one reviewer made the same point four times across two PRs, against a rule that is auto-injected into every agent turn. It only forbade constructing a sub-component inside a parent's __init__, so building one part-way through a run slipped past it, and it said nothing about when bad wiring must fail. Now: the graph is built at the entry point in one pass, and a mismatch raises there rather than degrading to a runtime fallback. Paid for by merging two overlapping paragraphs on constructor injection — the file grows by 4 lines for two new rules.

dev/guidelines/backend/testing.md — said "use dataclasses for parametrized cases" but never named the hybrid that got written. Now names it. Paid for by compressing the four-bullet "when to use" list that said one thing.

dev/guidelines/frontend/page-architecture.md — the no-mirroring rule was written for forms and useState, so URL state copied into a Jotai atom wasn't covered. Generalized to any state with an owner in the table above it.

Added

  • dev/knowledge/backend/query-pattern.md — pass limit/offset to the base Query constructor. Verified in core/query/__init__.py: execute() branches on self.limit or self.offset, so a subclass holding private copies leaves both None and gets query_with_size_limit()'s chunked re-execution on top of its own paging. Plus: read a collect() column with get_as_list_of_type.
  • .agents/rules/code-doc-style.md — spec vocabulary is as unreadable as a spec ID in a test name or docstring.
  • dev/guidelines/documentation.md — measurements go in as relative comparisons; the absolute figure depends on the environment it was taken in.
  • dev/guides/frontend/writing-component-tests.md — a test must fail when the behavior breaks: assert the value rather than the static text beside it, and check the component actually reads the flag the setup varies.
  • dev/guidelines/backend/python.md — the tasks/*.py function-local import exception (added in #10098) covers a thin wrapper, not logic hosted in tasks/. A task body needing a dozen deferred imports is saying the logic belongs elsewhere.

Pruned

  • dev/guidelines/frontend/typescript.md taught useMemo/useCallback dependency arrays while dev/knowledge/frontend/react.md says not to use them at all under the React Compiler. A reviewer had to ask which was right — the contradiction is the finding.
  • dev/knowledge/backend/schema-definitions.md pointed at an issue for "planned improvements" that closed on 2026-07-20.
  • dev/knowledge/backend/query-pattern.md was 520 lines against a 200–400 range, and this run adds to it, so its five near-identical result-dataclass walkthroughs collapse into one example plus an accessor table — which is where the get_as_list_of_type lesson naturally lands. The file ends at 459.

Sweep otherwise clean: no defect-snapshot notes survive, and the remaining #NNNN grep hits are git-workflow.md's issue-syntax examples and documentation.md's own rule text.

Context budget

+56 / −92 lines — net −36. Every file inside its range except query-pattern.md, which is 59 over after dropping 61 lines; splitting its ## Internals block is the next candidate and wants its own change. writing-component-tests.md is at 398 of 400, so the next lesson landing there compresses first.

FileLinesRange
dev/knowledge/backend/query-pattern.md459 (was 520)200–400
dev/guides/frontend/writing-component-tests.md398200–400
dev/guidelines/backend/testing.md403100–400
dev/guidelines/backend/python.md396100–400
.agents/rules/backend-component-design.md98—

Not lessons

#10106's keyset-pagination pair — ajtmccarty rejected it with reasoning and nothing landed. #10090's "SDK lacks IPAddress" and #10104's "missing author filter" — both bots retracted after being corrected. #10055's artifact-hard-coded failure fallback — real, but confined to that module. #10114's doc corrections and #10108's contradicted ADR claim — already covered by the verify-claims-against-the-diff rule root AGENTS.md gained last run. A "TIL", a screenshot request, and a jotai-naming aside — no rule.

How to test

Docs only. markdown-lint, validate-dev-guideline-links, and validate-documentation-style cover these paths in CI; uv run invoke docs.lint globs docs/docs/**, so it doesn't reach dev/ or .agents/. Relative links and code-fence balance checked locally.

🤖 Generated with Claude Code