docs: harvest review lessons from PRs merged 2026-07-24 to 2026-07-31
Why
Reviewers repeatedly had to spell out the same conventions across this week's PRs, because each lesson lived in a review thread and died there. This is a harvesting-review run over PRs merged 2026-07-24 → 2026-07-31 (the window since the last such run, #10032), turning feedback that generalizes into durable internal-doc conventions so a future author (human or agent) follows the convention the first time instead of a reviewer having to raise it again.
Each candidate lesson was reconstructed against the before/after code, verified against the current codebase, and checked against what's already documented before landing — per .claude/skills/harvesting-review/.
Stacked on #10030 (base: pha/conventions, which targets develop). Both PRs are harvest runs editing the same internal-doc layer, and they had independently arrived at the same rule — that a harvest which only ever adds makes the layer worse — so they land as one stack rather than colliding at the eventual stable → develop merge. GitHub will retarget this PR to develop automatically once #10030 merges.
Two places where the branches overlapped, reconciled here rather than left as duplicates:
- The skill's rot sweep and #10030's "Refine, don't accrete" say the same thing from opposite directions — this PR prunes backwards (rot already in the docs), #10030 bounds forwards (size ranges, cut what a new rule supersedes). The sweep now sits under that principle as its mechanical procedure, and the apply step applies both.
documentation.md: the no-file.py:linerule joins the sibling work-item-citation rule already in the Don't list, and #10030's "No provenance" bullet points at both instead of restating them.
ASGI Middleware split out of python.md — this run's path-matching lesson would have taken that file to 431 lines against its 100–400 range, and the rule #10030 introduces says a file at its limit gets split, not extended. It moves to dev/guidelines/backend/asgi-middleware.md with its own load-trigger entries; python.md ends at 393.
Because the base is develop-shaped again, the pruning fixes were re-applied to develop's copy of design-system.md (a newer table layout, its own five stale Migrated in #NNNN citations) rather than stable's older one.
Not restored, from the earlier stable retarget: four lessons were dropped when this branch was aimed at stable, because the code they describe doesn't exist there — the diff-tree/diff-list node-set fix (#10014), the merge-recompute.md invariant note (#9845), the Query.get_query_arrows() directional-Cypher lesson (#10053/#10019/#10082), and the ComputedAttribute generated-model-drift note (#9814). All four apply on develop and could be re-added; they are not in this PR. One example in dev/guidelines/backend/testing.md also remains genericized (StaleEntryCleaner rather than the real StaleLockCleaner from #10031) — harmless, since the rule doesn't depend on the name.
Rounds of follow-up before the stack, all from user review:
- The "no
file.py:linecitations" lesson had been mis-routed into.agents/rules/code-doc-style.md(a source-code comment/docstring rule, auto-injected on every turn touching.py/.ts/.tsx) by extending itspathsfrontmatter to also cover markdown docs. Re-homed todev/guidelines/documentation.mdinstead, next to the sibling PR/spec-citation rule it belongs beside. Also dropped a "known gap" note that described a current code defect rather than a durable convention. - Added a "sweep for rot" step to the skill and reported 19 pre-existing citation-rot hits elsewhere in the docs — but didn't fix any of them. Called out for describing debt instead of removing it. Went back and fixed all 19 (dropped stale
PR #NNNN/Migrated in #NNNNcitations across 5 files, kept the underlying prose), and while verifying one file's citations against current code, found the rot wasn't just stale line numbers —templates.mdcited a method,Node._apply_template(), that no longer exists (renamed tohandle_object_template()); fixed that too. Also tightened the skill itself so this doesn't recur: §5's "report the rest as a punch list" escape hatch is gone — every mechanical hit is now expected to be fixed in the same PR, not deferred. - Retargeted to
stable, which required dropping or adapting the develop-only-feature lessons rather than mechanically replaying the same diff onto a base where they don't apply. Superseded by the stack: the three commits are squashed into one, replayed ontopha/conventions, and thestableadaptations reversed wheredevelophas the real code.
Source PRs (audited against develop, where all twelve were merged)
Twelve PRs (one cluster of three related PRs counted once) were audited, one subagent per PR:
- #10062 (perf: id-only relationship hydration) — cubic: no benchmark exercised the id-only fast path, so CI couldn't have caught a regression.
- #10014 (fix: diff tree dropping unchanged-parent nodes) — cubic: Jotai/mock/URL state leaking between component tests in the same file; pa-lem: the diff tree and the changed-nodes list must not share one filtered node set (bug recurred twice in the same PR, once per filter) — plus a "safe by construction" non-null-assertion trap on a re-derived
Maplookup. (lesson dropped from this PR — feature not onstable, see above) - #10059 (refactor: Apollo → urql) — pa-lem: a lazily-memoized module-level client cache has no test-reset hook, so state leaks across tests in the same file.
- #9814 (feat: user-facing write/read schema split) — ajtmccarty:
tasks/*.pybackend imports must stay function-local (asked 4 times in one PR); cubic: a generatedComputedAttributesub-model is hand-duplicated from its canonical model with no drift guard. (the drift-guard lesson dropped from this PR — feature not onstable, see above) - #9879 (feat: API backpressure) — cubic: path-exclusion matching used a bare
startswith(and the same bug still lives, unfixed, inConditionalGZipMiddleware); ajtmccarty's DI/observer and settings-at-boundary findings substantially overlap with the still-open #10065, so they were not duplicated here. - #10038 (feat: selective post-merge regeneration) — cubic: 5 threads on stale
file.py:linecitations indev/specs/dev/knowledgedocs; a second optional filter field whose emptiness got conflated with "no filter at all"; a test whose final assertion converges via two different code paths. - #10053 / #10019 / #10082 (uniqueness-constraint scoping cluster) — cubic: an undirected
IS_RELATEDmatch over-resolves a self-referential relationship (dropped from this PR — helper not onstable, see above); a reused component'sinitialize()reset its index but left a sibling cache stale. - #9845 (fix: recompute on deleted read peer) — ajtmccarty: a changelog fragment can be named after a Jira ID instead of a GitHub issue number (3 already-broken links exist in
CHANGELOG.mdfrom this exact mistake); cubic: a new fallback branch in the coalesced recompute resolver only widened one of the two symmetric targets it needed. (the recompute-invariant lesson dropped from this PR — feature not onstable, see above) - #10034 (perf: batch Python-transform recompute) — ajtmccarty:
add_tags()mid-run silently drops an earlier call's tags; the documented fix (indev/knowledge/backend/async-tasks.md) isn't linked from the guide that teaches the unsafe pattern. - #10031 (fix: merge failure recovery) — polmichel: a mutation method returned a value that only the test consumed (example genericized for
stable, see above); a component should take a capability-scopedProtocoleven outside a "should I mock?" trigger (overlaps with #10065, not duplicated).
Also scanned with no durable lesson: #10051 (single bot thread, rebutted correctly, no fix landed).
Not duplicated: several DI/observer/config-validation findings from #9879 and #10052 (audited in this run's research but not turned into edits here) are already comprehensively covered by the still-open #10065 — landing a competing edit to the same sections would conflict rather than help.
What changed
New rules/knowledge added:
dev/knowledge/backend/testing.md: a benchmark must exercise the exact input shape a conditional perf optimization is gated on.dev/guides/frontend/writing-component-tests.md: reset shared Jotai atoms / clear mocks / reset URL state between tests in the same file.dev/guidelines/backend/python.md:tasks/*.pyimports stay function-local (documented exception to the top-of-file rule); a path-exclusion check must not use a barestartswith.AGENTS.md: verify a specific identifier/metric/config-default claim against the diff before writing it into a changelog fragment, PR description, or ADR..agents/rules/backend-component-design.md: a component'sinitialize()/reset()must clear every derived cache, not just the field it obviously replaces.docs/docs/development/changelog.mdx+.agents/skills/creating-changelog-entries/SKILL.md: changelog fragment names must use the GitHub issue number or+, never an internal tracker ID.dev/guidelines/backend/testing.md: don't add a return value to a mutating method just so a test can assert on it; when a result is reachable via two different code paths, assert an intermediate signal too.dev/guidelines/frontend/typescript.md: aMaplookup seeded from the same array you index it with is still a type lie if asserted with!.dev/guidelines/documentation.md: nofile.py:linecitations in internal docs.
Strengthened existing coverage (rule existed but a reviewer still had to raise it):
dev/guides/frontend/writing-unit-tests.md: added the module-level-singleton-needs-a-reset-hook case to the existing "keep tests independent" guidance.dev/guides/backend/creating-async-tasks.md: added a caution + cross-link to the already-documentedadd_tags()pitfall right where the guide teaches the pattern that reproduces it.
Pruned (from the skill's new §5 sweep):
dev/guidelines/frontend/page-architecture.md,route-architecture.md,dev/knowledge/frontend/shared-components.md,design-system.md: dropped 17 stalePR #NNNN/Migrated in #NNNNcitations total (12 found viadevelop's copies, 5 more found instable's separately-structureddesign-system.mdtable), kept the underlying prose.dev/knowledge/backend/templates.md: dropped 4 stalefile.py:linecitations and fixed a renamed-method reference (_apply_template()→handle_object_template()) surfaced while verifying them.
Skill maintenance:
.agents/skills/harvesting-review/SKILL.md: added §5 "Sweep for rot" — every run now greps the destination layer for stale citations, fixed defect-snapshots, and superseded narrow rules, and fixes them in the same PR (tightened after the first pass only reported findings without acting on them). Added a guardrail against writing defect-snapshot content as permanent docs in the first place.
Docs-only — no code, no generated files, no schema.
How to review
None of the edits touch the sections #10065 is already changing. Everything here lands in dev/guidelines/, dev/knowledge/, dev/guides/, docs/docs/, .agents/skills/, or a .agents/rules/* addendum to an existing file (no new .agents/rules/* file, so no added per-turn token cost). Given the base is stable, the diff intentionally omits any lesson tied to develop-only code — see the "Why" section for exactly which four were dropped and why.
How to test
PATH="$PWD/docs/node_modules/.bin:$PATH" uv run invoke docs.lint
0 errors (pre-existing, unrelated markdownlint warnings elsewhere, unchanged by this PR).
Impact & rollout
- Backward compatibility: docs-only, no runtime impact
- Deployment notes: safe to merge
Checklist
- Tests added/updated (n/a — docs-only)
- Changelog entry added (n/a — internal docs)
- 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