docs: harvest review lessons from last week's PRs into internal docs

Merged
SA
4mo ago
+34-6

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 @flow functions 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 with len() on a list read (use get_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 catalogue WorkflowDefinition, 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 develop with 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/**/*.ts and frontend/app/src/**/*.tsx.