docs: harvest review lessons from PRs reviewed 2026-08-14 to 2026-08-21

[saltas888]

Why

Reviewers repeated the same findings across this week's PRs — most of all on the dark-theme token migration, where the same three findings (token swap ≠ no-op, WCAG demotions, missing changelog fragments) recurred across ten PRs. This is the weekly harvest run: it mines those threads for rules that generalize, verifies each against the code, and routes the durable ones into the internal-doc layer.

Non-goals: no production code or test changes; no duplication of edits pending in #10030 (pha/conventions, on develop) — in particular the changelog-skill naming refinements already fixed there.

PRs harvested from

Lessons in this PR trace to review threads on:

• refactor(frontend): tokenize the sheet frame and surface colors #10267, refactor(frontend): add Card secondary and panel surface variants #10269, refactor(frontend): migrate de-emphasized text to semantic color tokens #10272, feat(frontend): add dark palette for existing css variables #10273, refactor(frontend): tokenize input surfaces for dark mode #10274, refactor(frontend): adapt button variants to dark theme #10276, refactor(frontend): tokenize hover and focus surfaces for dark mode #10278, refactor(frontend): add a selected token for list box selection #10279, refactor(frontend): add dark theme for data table surfaces #10280, refactor(frontend): adapt tree and selection surfaces to dark theme #10282, Adapt remaining app to dark theme #10284, fix(frontend): theme the surfaces that stayed light in dark mode #10295 (dark-theme token migration series) — theme-token discipline: a token swap is a visual change unless the rendered value is identical, palette-family consistency, WCAG AA tiers for text tokens, fixed-scheme surfaces, sibling-control consistency, no dead tokens; and the repeated missing-changelog-fragment finding
• docs: document how query targeting scopes artifact regeneration [IFC-2504] #10293 (query targeting docs) — verify SDK/infrahubctl claims against the pinned python_sdk commit, never bump the pin to make docs resolve (two bot false positives rebutted with git -C python_sdk show); GitHub's renderer does not follow repo symlinks in relative links (the specs → dev/specs case)
• test: stop the webhook traceback fixture from reconfiguring logging process-wide #10322 (webhook traceback fixture) + feat(backend): map uniqueness violations to a UNIQUENESS_VIOLATION code #10228 (uniqueness error codes) — never document what the code does not do (two maintainers asked for such docstrings/comments to be deleted); say "object" not "node" in user-facing text
• docs: cover branch rebase in the upgrade docs #10311 (upgrade docs) — don't reference procedure steps by number
• chore(backend): enforce ruff TRY400 so error logs carry tracebacks #10220 (ruff TRY400) — branch targeting for lint/tooling PRs: rule enablement that rewrites runtime call sites is develop work; config/docs-only tooling may target stable
• fix(graphql): reject user-supplied branched_from on branch creation #10306 (reject user-supplied branched_from) — deprecation messages name the removal version
• fix(backend): retire branch-agnostic field edges on object deletion (… #10312 (retire branch-agnostic edges) — instance-level relationship self-loops are unsupported (maintainer statement rebutting a bot P2)
• feat(regeneration): narrow relationship-reached changes to owning members (IFC-2946) #10262, fix(backend): update profile/template instances during schema name/namespace/inheritance update #10277, chore(deps): upgrade prefect-redis to 0.2.14 #10300 (changelog-fragment threads) — fed the root AGENTS.md "changelog fragment for any user-visible change / none for pure internal changes" line

Also read, with nothing durable to harvest (no in-window substantive threads, lessons already codified, or PR-local design calls): #10312's transaction threads, #10353, #10358, #10354, #10339, #10334 (its maintainer corrections land in that open docs PR), #10341, #10348, #10347, #10331, #10335, #10290, #10250, #10238, #10298, #10299, #10302, #10316, #10317, #10287, #10288, #10291, #10281, #10256, #10231, #10266, #10270, #10030, #10178, #10232, #10135, #10258, #9451, #9965, #10164, and the bot merge/submodule/dependabot PRs in the window.

Notable non-edits, recorded deliberately:

• to IS NULL on active-edge reads recurred on keep earliest create user as created_by during merge #10281 hours after docs: harvest review lessons from PRs reviewed 2026-08-07 to 2026-08-14 #10259 codified exactly that rule in dev/knowledge/backend/database-schema.md — the comment predates the doc's merge, so no further edit; worth watching whether it recurs now the rule is live.
• feat(regeneration): narrow relationship-reached changes to owning members (IFC-2946) #10262's layering thread (core importing RelationshipHop/ReachedPath from infrahub.graphql.analyzer) is unresolved with no landed fix, and infrahub.core already imports from infrahub.graphql in 8 places on stable — writing a "never" rule would contradict the tree, so this is flagged here instead of codified.
• docs: document how query targeting scopes artifact regeneration [IFC-2504] #10293's ADR-criteria question ("our guidelines to define what should be an ADR aren't clearly defined" — dgarros) is a genuine gap that wants a team decision, not a harvest edit.
• Branch isolation ("non-isolated branches do not exist anymore", fix(backend): retire branch-agnostic field edges on object deletion (… #10312) is already encoded in code via the GraphQL deprecation_reason on is_isolated.

What changed

Grouped by intent (documentation layer only, 10 files, +42/−7):

• Frontend theming (dev/guidelines/frontend/styling.md, new "Theme tokens" section): the five rules above, written as imperatives with the concrete failure shapes reviewers kept describing. The token system lives on develop; this lands on stable and reaches it through the routine stable→develop syncs, same as the rest of the harvest.
• Changelog discipline (root AGENTS.md, Always Do): one line — towncrier fragment for any user-visible change, UI styling included; none for pure internal changes. The rule already exists in the creating-changelog-entries skill; this is the load-trigger that was missing (≥8 repeat comments this week).
• Docs claim verification (docs/AGENTS.md): the existing verify-claims bullet now names the pinned-submodule check for SDK features; new terminology line — "object", not "node", in user-facing text.
• Links (dev/guidelines/markdown.md): relative links must not route through repo symlinks.
• Comment style (.agents/rules/code-doc-style.md): never describe what the code does not do.
• Docs style (dev/guidelines/documentation.md): don't reference steps by number.
• Branch targeting (dev/guidelines/git-workflow.md): the lint/tooling split, codifying the precedent argued on chore(backend): enforce ruff TRY400 so error logs carry tracebacks #10220.
• Backend knowledge (dev/knowledge/backend/schema-definitions.md, database-schema.md): deprecations name the removal version; instance-level self-loops unsupported.
• Rot sweep (dev/knowledge/frontend/design-system.md): five stale "Migrated in #NNNN" citations removed — develop's copy already dropped them; stable's diverged copy still carried them.

What stayed the same: no production code, no tests, no user-facing docs pages, no schema changes.

How to review

Every edit cites a real review thread (see the commit message for the per-file mapping). The judgement calls worth a second pair of eyes: the git-workflow branch-targeting bullet encodes @saltas888's rebuttal on #10220 that no maintainer overruled — flag it if the release-vehicle policy reads differently; and the self-loop line in database-schema.md encodes @ajtmccarty's statement on #10312.

File sizes after the change: every touched file is inside its repository-organization.md range (styling.md 106/100–400, database-schema.md 390/200–400 — closest to its cap).

How to test

markdownlint-cli2 <the 8 edited non-AGENTS md files>

Ran locally: 0 errors (AGENTS.md files are excluded by the repo's markdownlint config; Vale not available in the sandbox; no docs/docs pages touched).

Impact & rollout

• Backward compatibility: documentation only; no behavior change.

Checklist

• Tests added/updated — N/A, docs only
• Changelog entry added — N/A, internal docs only
• External docs updated — N/A, no user-facing change
• 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_01XdeNcpTLZ15aUaz6H5uJVd

---

Generated by Claude Code

[cubic-dev-ai]

All reported issues were addressed across 10 files

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. This PR codifies recent review feedback into the project's internal documentation and developer guidelines, covering theming, changelog discipline, and documentation standards.

Re-trigger cubic</sub>