docs: update Claude docs from PR review analysis

[claude]

Summary

Weekly analysis of PR review comments (2026-07-20 -> 2026-07-27).
Analyzed 11 PRs with 72 review threads. Found 8 actionable insights (cumulative across all runs on this branch).

Changes

agent_docs/conventions.md

• Passthrough services must still extend BaseService
  Source: PR feat(integration-service): add Execution passthrough #557 — reviewer claude flagged that Execution bypassed BaseService entirely, forcing as unknown as casts in tests and losing standard auth-flow integration.

  "Execution must extend BaseService. The project convention states: 'Services follow the pattern: extend BaseService.' Every other HTTP service class in the repo extends BaseService — Execution is the sole exception."

• Raw fetch() callers must manually add distributed-tracing headers
  Source: PR feat(integration-service): add Execution passthrough #557 — reviewer claude noted that execute() using raw fetch() was invisible to the platform's distributed-tracing infrastructure.

  "ApiClient.request() generates a traceparent / x-uipath-traceparent-id header pair on every request. By using raw fetch(), execute() is invisible to the platform's distributed-tracing infrastructure."

• @track both segments must be PascalCase
  Source: PR from previous run — camelCase method names in @track break dashboard queries.

agent_docs/rules.md

• Read-modify-write patterns need a dedicated cast test
  Source: PR feat(data-fabric): align entity create field names with get response #619 — reviewer claude identified that updateById's internal cast back to the raw wire field name (isInsightsEnabled) had no test, leaving a silent failure mode if the cast drifted to the renamed SDK field.

  "If this cast ever drifted to .isAnalyticsEnabled (which is undefined on the wire response), every updateById call would silently send isInsightsEnabled: false, disabling analytics without any error or test failure."

• Snapshot+restore: restore value must come from snapshotted state
  Source: PR feat(subscriptions): topic-level updates (PR 5/7) #517 — reviewer claude caught that updateCategories integration test hardcoded isSubscribed: true for the restore step instead of reading the original state.

  "The restore step hardcodes isSubscribed: true instead of reading the original state first. If the tenant's Error–Email category was already unsubscribed before the test, the 'restore' actually mutates the environment."

• Unit test file paths must mirror src/ directory structure exactly (from previous run)

• Use .rejects.toBeInstanceOf(ErrorType) consistently (from previous run)

• Do NOT use @throws in {Entity}ServiceModel JSDoc (from previous run)

• NEVER embed PR-specific notes or follow-up references in JSDoc (from previous run)

No changes

• CLAUDE.md — no relevant insights
• Agents.md — no relevant insights
• agent_docs/architecture.md — no relevant insights

PRs Analyzed

PR	Title	Comments
#619	feat(data-fabric): align entity create field names with get response	4
#556	feat(integration-service): add Elements service	7
#557	feat(integration-service): add Execution passthrough	3
#591	fix(data-fabric): multi-join queries were silently no-ops	10
#555	feat(integration-service): add Connectors service	6
#604	feat(traces): route governance endpoints via llmops base	1
#517	feat(subscriptions): topic-level updates (PR 5/7)	5
#606	feat(samples): add document-validation-subcomponents sample app	6
#602	docs: add Template Gallery + docs PR preview workflow	17
#595	ci: add sample-app PR gate	11
#598	docs(sdk-review): calibrate for sample-app diffs	1

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.