docs(guidelines): internal-doc writing style, size discipline, six harvest runs

Closed
SA
3mo ago
+553-287

Why

Reviewers kept raising the same things, and each lesson lived in a review thread and died there. This PR consolidates six /harvesting-review passes over PRs reviewed 2026-07-16 → 2026-08-07 into the internal-doc layer, so a future author (human or agent) follows the convention the first time. It also introduces the discipline the harvests themselves turned out to need: a harvest that only adds makes the layer worse, so every addition here is paid for with compression or pruning.

Every lesson was reconstructed against the before/after code, verified against the current codebase, and checked against existing coverage before landing, per .agents/skills/harvesting-review/.

Closed in favor of this PR (their commits are cherry-picked here): #10098, #10145, #10157.

Docs only — no code, no generated files, no schema.

The conventions now in place

One row per lesson: the source PR whose review surfaced it, and where it now lives.

Backend

ConventionLives inSource
Ask whether the try/except is needed at all; # noqa: BLE001 needs a named reason; inside a transaction a caught-and-returned failure commits (verified against InfrahubDatabase.__aexit__)dev/guidelines/backend/exceptions.md (new, split from python.md)#10002
Don't write T | Sequence[T] unions — take Sequence[T] and let callers wrap (a bare str satisfies Sequence[str] and gets shredded)dev/guidelines/backend/python.md#10079
tasks/*.py backend imports stay function-local — and the exception covers a thin wrapper, not logic hosted in tasks/dev/guidelines/backend/python.md#9814, #10095
A path-exclusion check must not use a bare startswithdev/guidelines/backend/asgi-middleware.md (new, split from python.md)#9879
retry_db_transaction replays the whole wrapped scope (on TransientError or EntityNotFound): wrap only rollback-able scopes, skip under db.is_transaction, mind nested retried callersdev/knowledge/backend/mutations.md#10121
Pass limit/offset to the base Query; insert_limit = False without an own LIMIT never finishes paging; auto-pagination needs a total-order ORDER BY; read collect() columns with get_as_list_of_typedev/knowledge/backend/query-pattern.md#10106, #10132
n.kind is concrete-only — generics exist as labels; type concrete-only query inputs as list[NodeSchema]dev/knowledge/backend/database-schema.md#9805
Changelog models mask secrets only at construction — post-construction assignment leaks themdev/knowledge/backend/events.md#10105
InfrahubBatch is concurrent, not ordered; the best-effort contract also covers a single inline side effect; add_tags() mid-run drops earlier tags (cross-linked where the guide teaches the pattern)dev/knowledge/backend/async-tasks.md, dev/guides/backend/creating-async-tasks.md#10113, #10034
Fix data bugs in the migration layer, not lazily in save(); per-item try/collect into MigrationResult.errors; batch by the memory-bounding unitdev/guides/backend/creating-migrations.md (now routed from backend/AGENTS.md — it was loaded by nothing)#10105, #10132
A new Settings field must reach the hand-maintained development/ compose anchor, not just the generated onedev/guidelines/backend/checklist.md Configuration#10122
New REST endpoints join Ask First — extend the existing GraphQL query insteadbackend/AGENTS.md#8594

Backend testing

ConventionLives inSource
Verify wiring by parsing source (ast/inspect), never by instrumenting production codedev/guidelines/backend/testing.md, .agents/rules/testing-python.md#10121
Don't add a return value just so a test can assert on it; assert an intermediate signal when a result converges via two code pathsdev/guidelines/backend/testing.md#10031, #10038
Poll, don't sleep, for async outcomes; make removal assertions branch-attributable; extract a pure function before claiming the cheap test tier is unreachabledev/guidelines/backend/testing.md#10133, #10132, #10137
Parametrize with dataclasses — the dict-keys-plus-in-test-lookup hybrid is now named and forbiddendev/guidelines/backend/testing.md#10095
A benchmark must exercise the exact input shape a conditional optimization gates ondev/knowledge/backend/testing.md#10062

Frontend

ConventionLives inSource
Reset shared Jotai atoms, mocks (vi.resetAllMocks), and URL state between tests in one filedev/guides/frontend/writing-component-tests.md#10014
A test must fail when the behavior breaks: assert the value, not the static text beside it; check the component actually reads the flag the setup variesdev/guides/frontend/writing-component-tests.md#10111, #10128, #10129
A lazily-memoized module-level singleton needs a test reset hookdev/guides/frontend/writing-unit-tests.md#10059
A Map lookup seeded from the array you index it with is still a type lie under !dev/guidelines/frontend/typescript.md#10014
Don't mirror owned state (URL, forms, server) into a Jotai atom — generalized from the old forms-only ruledev/guidelines/frontend/page-architecture.md#10111

Component design and code style (.agents/rules/ — edits to existing rules, no new files)

ConventionLives inSource
Build the component graph at the entry point in one pass; a wiring mismatch raises at construction, not as a runtime fallback; initialize()/reset() clears every derived cache.agents/rules/backend-component-design.md#10055, #10053/#10019/#10082
Spec vocabulary is as unreadable as a spec ID in a test name or docstring.agents/rules/code-doc-style.md#10096

Process and documentation

ConventionLives inSource
PR ceremony scales with the change: no changelog fragment or dev/specs/ scaffolding on a trivial fix; a lint-suppression PR ships the suppression only and files the bug separatelydev/guidelines/git-workflow.md, dev/guidelines/repository-organization.md#10018, #10079
Internal-doc writing style: rule first, plain words, no provenance, no padding, a size budget, pay-for-itdev/guidelines/documentation.md For Internal Docsthe harvests themselves
No file.py:line citations in internal docs; measurements go in as relative comparisonsdev/guidelines/documentation.md#10038, #10108
Verify identifier/metric/config-default claims against the diff before writing them into fragments, PR text, or ADRsroot AGENTS.md#9845 et al.
Changelog fragments: GitHub issue number or +, never a tracker ID; the + orphan-prefix failure mode; housekeeping is not a catch-all — no user-facing effect means no fragment.agents/skills/creating-changelog-entries/SKILL.md, docs/docs/development/changelog.mdx#9845, #10146/#10147, #10018
invoke lint runs ruff check --diff, blind to unfixable violations — /pre-ci carries the CI-parity ruff check step.agents/commands/pre-ci.md, root AGENTS.md#10146/#10147
Don't escalate from a stale "commits behind" count.agents/skills/monitoring-pull-requests/SKILL.md#10146
Grafana dashboards: defined datasource variables only, sweep every link surface, regenerate the standalone compose from development/development/grafana/AGENTS.md (new)#10153
Excalidraw exports: opaque white backgrounddocs/AGENTS.md#9953

Pruned in the same PR

Stale PR #NNNN/Migrated in #NNNN citations across 5 frontend docs (17 hits) and templates.md (4 hits, plus the renamed method the rot was hiding: _apply_template() → handle_object_template()); typescript.md's useMemo dependency-array teaching, which contradicted react.md's React-Compiler guidance — a reviewer had to ask which was right; schema-definitions.md's pointer to an issue closed 2026-07-20; query-pattern.md's five near-identical walkthroughs collapsed into one example plus an accessor table (520 → 459).

The harvesting-review skill, final state (0.8.0)

Refine, don't accrete leads the skill and outranks its other rules: measure the target file against its size range first, compress or split a file at its limit (repointing every inbound reference, including .agents/skills/.agents/commands routes), cut what the new rule supersedes, and report added/removed line counts — zero deletions is a finding about the harvest. Every run sweeps the destination layer (including .agents/rules) for citation rot, fixed defect-snapshots, and superseded narrow rules, and fixes every hit in the same PR — a punch list is not pruning. A lesson whose root cause is a fragile pattern becomes a rule steering away from the pattern, not a survival guide for it. A lesson owned by an existing skill (creating-changelog-entries, pre-ci, the org plugin's pruning-residues) is routed into that skill instead of parallel dev/ prose.

Also decided along the way

  • Base branch — develop, deliberately (cubic suggested stable, discussed with @polmichel): git-workflow.md has no docs-target-stable rule, the lessons were verified against develop's code, and several describe modules that don't exist on stable. If internal-docs-to-stable should be policy, that's a git-workflow.md rule to add first.
  • Dropped, not restored: four develop-only lessons from a brief stable retarget (diff-tree node sets #10014, merge-recompute invariant #9845, get_query_arrows() #10053-cluster, ComputedAttribute drift guard #9814) — re-harvestable later.
  • Read with nothing durable: #10051, #10090, #10104 (bot findings retracted), #10123, #10125, #10136, #10114 (already covered by the verify-claims rule), #10141, #10154, #10149, #10144, #10099, #10124, #10080, #10089, #10081, #7569, and a set of bare approvals.
  • Confirmed-real code issues flagged as follow-ups, not codified: migrations/query/attribute_add.py missing the documented r.status ASC tiebreaker; develop's dashboards carrying 42 undefined-$datasource references (#10153 fixed them only on release-1.11); changelog/models.py's set_value_previous bypassing the masking validator; #10133's broker-durability lessons parked until the Redis driver merges; the stable/develop ruff BLE divergence.
  • All review feedback on this PR addressed in-branch (@polmichel's six comments, cubic's two rounds — every finding verified against code before fixing): the str/Sequence doc section became the rule against the pattern, the extract skill's error-handling route repointed to exceptions.md, backend/AGENTS.md's list made contiguous, the retry-trigger wording completed, the test examples made reproducible and actually-isolating, vi.resetAllMocks over clearAllMocks, and the Grafana regeneration command corrected.

Context budget

+702/−338 over develop (40 files, after merging develop back in), and the shape matters more than the total: no new file in .agents/rules/ (the only layer injected into every agent turn — three existing rules edited), the two python.md splits load only on their trigger, and every harvest paid with deletions.

FileLinesRange
dev/knowledge/backend/query-pattern.md490200–400 — the ## Internals split is the flagged next change
dev/guidelines/backend/python.md414100–400 — the ASGI split had it at 393; develop-side additions re-grew it; the next split is its own change
dev/guides/frontend/writing-component-tests.md398200–400
dev/guidelines/backend/testing.md393100–400

How to test

Docs only. markdown-lint (docs/docs), validate-dev-guideline-links (lychee over dev/**, backend/**), and validate-documentation-style (Vale over docs/) cover these paths in CI; relative links, section anchors, and code-fence balance checked locally across all 37 changed markdown files.

🤖 Generated with Claude Code