docs: harvest review lessons from last week's PRs into internal docs
Why
Reviewers repeated the same guidance across last week's PRs — thin Prefect flows, page-limit traps, narration comments — because each lesson lived in a review thread and died there. This is a harvesting-review run over the PRs reviewed 2026-07-14 → 2026-07-21, turning the feedback that generalizes into durable internal-doc conventions so a future author (human or agent) follows the convention the first time.
Non-goals: no lessons from still-open PRs whose pattern isn't in-tree yet (#9965 custom-scalar conventions, #9970 attribute-kind enumerations, #9948 react-aria popover gotcha), and nothing already codified on develop (#9977's wrong-type/checker-re-enable rule, the exception-handling section) or in-flight inside an open PR (#9805's registry hot/cold-path edit to query-pattern.md).
Source PRs
Lessons were learned from the review threads of:
- #9932, #9849, #9805 — ajtmccarty, repeatedly: Prefect flows should be thin wrappers around dependency-injected components; singleton getters belong at entry points
- #9805 — dgarros: pull workflow names from the catalogue, not hardcoded strings; cubic:
len(Branch.get_list(...))under-counts past the page limit - #9941 — cubic: a Prefect-artifact capture write must never flip a successful webhook delivery to failed; artifact listings must paginate before pick-latest
- #9879 — cubic: metrics-observer callbacks must be exception-isolated from lock/pool state
- #9980 — ajtmccarty: rejected extracting duplicated Cypher into Python fragment builders — inline readability wins
- #9871 — cubic: frontend permission gate didn't mirror backend DENY-preemption; bilalabbad: narration comments
- #9880, #9814, #9942, #9952, #9977 — bilalabbad, ajtmccarty, polmichel: recurring "remove comments that narrate what the code does" feedback on both frontend and backend
Also scanned with no new lessons to harvest (already covered, PR-local, or no substantive review): #9815, #9893, #9923, #9924, #9928, #9930, #9937, #9938, #9939, #9943, #9944, #9947, #9956, #9963, #9631.
What changed
Strengthened existing coverage (rule existed but wasn't landing):
dev/knowledge/backend/async-tasks.md+dev/guides/backend/creating-async-tasks.md: the knowledge doc literally said flow functions "contain business logic", contradicting the DI guidance reviewers gave on three separate PRs. Rewritten: flows are thin composition roots — resolve singletons at the flow entry, build the component, delegate. Guide + checklist updated to match..agents/rules/backend-component-design.md: one paragraph naming@flowfunctions as the application entry points where singleton getters are resolved.dev/knowledge/backend/query-pattern.md: the page-limit warning now spells out its two recurring corollaries — never derive a count withlen()on a list read (useget_list_count), and pick-latest reductions over paginated APIs must page through all results first..agents/rules/code-doc-style.md: extended from backend-only paths to frontend*.ts/*.tsx— the no-narration-comments rule existed but reviewers kept having to raise it on frontend PRs it didn't apply to.
New rules:
dev/knowledge/backend/async-tasks.md: reference workflow names via the catalogueWorkflowDefinition, never re-typed string literals; observability side-writes (capture artifacts, metrics callbacks) are best-effort and never change the primary operation's outcome.dev/knowledge/backend/query-pattern.md: keep Cypher readable inline — don't extract shared fragments into Python string-building helpers just to dedupe.dev/knowledge/backend/permissions.md: any client-side re-implementation of the permission check must mirror backend DENY-preemption semantics.
What stayed the same: docs-only — no code, no generated files, no schema.
How to review
The two .agents/rules/* edits deserve the most scrutiny — they auto-inject into every agent turn, so their token cost is paid repo-wide. Everything else loads only via the router. The async-tasks.md flow-function rewrite is the highest-value fix (it corrected an active contradiction); the rest are one-paragraph additions to existing sections.
How to test
docs/node_modules/.bin/markdownlint-cli2 dev/knowledge/backend/async-tasks.md dev/knowledge/backend/query-pattern.md dev/knowledge/backend/permissions.md dev/guides/backend/creating-async-tasks.md .agents/rules/code-doc-style.md .agents/rules/backend-component-design.md
The only reported errors are pre-existing in untouched sections of permissions.md.
Impact & rollout
- Backward compatibility: docs-only, no runtime impact
- Deployment notes: safe to merge; flows down to
developwith the next stable→develop 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
https://claude.ai/code/session_01B8k1FwDp5KZ5sAWbhrVmd5
Generated by Claude Code
Summary by cubic
Docs-only update harvesting recurring review feedback into internal guides and /.agents rules to prevent repeat comments. Clarifies thin Prefect flows, safe pagination, readable Cypher, comment style (now applies to TS/TSX), permission semantics, and telemetry isolation.
- New Rules and Clarifications
- Flows are thin composition roots: resolve singletons at the flow entry, inject into a component, and delegate (logic lives in the component).
- Reference workflow names via the catalogue
WorkflowDefinition, not string literals. - Observability writes (artifacts, metrics callbacks) are best-effort and exception-isolated; they must never change the primary outcome.
- Pagination: do not use
len()on page-limited reads; use count methods and paginate fully before any “pick latest/best” reduction. - Keep Cypher readable inline; avoid Python fragment builders used only to dedupe.
- Frontend permission gates must mirror backend DENY-preemption semantics.
- Extend “no narration comments” rule to
frontend/app/src/**/*.tsandfrontend/app/src/**/*.tsx.