docs: harvest review lessons from PRs reviewed 2026-07-31 to 2026-08-06
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.
| PR | What review surfaced |
|---|---|
| #10055 | ajtmccarty ×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 |
| #10058 | ajtmccarty: inject SchemaManager instead of reaching for registry; a predicate living on the model |
| #10095 | ajtmccarty: 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 |
| #10106 | gmazoyer ×2: a Query subclass keeping its own limit/offset; get_as_list_of_type existing and being missed |
| #10096 | gmazoyer: spec vocabulary in a test name that means nothing without the spec |
| #10108 | ajtmccarty: an absolute performance figure in an ADR. cubic: an ADR claim the code contradicts |
| #10111 | saltas888: URL state mirrored into a Jotai atom. cubic: a toast assertion that passes with the wrong branch name |
| #10128 | saltas888: is a useMemo still needed under the React Compiler? cubic: an isFetching flag the provider never reads, making its test inert |
| #10129 | cubic ×3: "main" → is_default behavior changes with no test exercising a non-main default |
| #10114 | ajtmccarty ×3: doc claims about merged-branch behavior the code contradicts |
| #10090, #10104 | bot findings retracted after a human corrected them |
| #10123, #10125, #10136 | scanned, 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— passlimit/offsetto the baseQueryconstructor. Verified incore/query/__init__.py:execute()branches onself.limit or self.offset, so a subclass holding private copies leaves bothNoneand getsquery_with_size_limit()'s chunked re-execution on top of its own paging. Plus: read acollect()column withget_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— thetasks/*.pyfunction-local import exception (added in #10098) covers a thin wrapper, not logic hosted intasks/. A task body needing a dozen deferred imports is saying the logic belongs elsewhere.
Pruned
dev/guidelines/frontend/typescript.mdtaughtuseMemo/useCallbackdependency arrays whiledev/knowledge/frontend/react.mdsays 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.mdpointed at an issue for "planned improvements" that closed on 2026-07-20.dev/knowledge/backend/query-pattern.mdwas 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 theget_as_list_of_typelesson 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.
| File | Lines | Range |
|---|---|---|
dev/knowledge/backend/query-pattern.md | 459 (was 520) | 200–400 |
dev/guides/frontend/writing-component-tests.md | 398 | 200–400 |
dev/guidelines/backend/testing.md | 403 | 100–400 |
dev/guidelines/backend/python.md | 396 | 100–400 |
.agents/rules/backend-component-design.md | 98 | — |
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