docs(guidelines): internal-doc writing style, size discipline, six harvest runs
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
| Convention | Lives in | Source |
|---|---|---|
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 startswith | dev/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 callers | dev/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_type | dev/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 them | dev/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 unit | dev/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 one | dev/guidelines/backend/checklist.md Configuration | #10122 |
| New REST endpoints join Ask First — extend the existing GraphQL query instead | backend/AGENTS.md | #8594 |
Backend testing
| Convention | Lives in | Source |
|---|---|---|
Verify wiring by parsing source (ast/inspect), never by instrumenting production code | dev/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 paths | dev/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 unreachable | dev/guidelines/backend/testing.md | #10133, #10132, #10137 |
| Parametrize with dataclasses — the dict-keys-plus-in-test-lookup hybrid is now named and forbidden | dev/guidelines/backend/testing.md | #10095 |
| A benchmark must exercise the exact input shape a conditional optimization gates on | dev/knowledge/backend/testing.md | #10062 |
Frontend
| Convention | Lives in | Source |
|---|---|---|
Reset shared Jotai atoms, mocks (vi.resetAllMocks), and URL state between tests in one file | dev/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 varies | dev/guides/frontend/writing-component-tests.md | #10111, #10128, #10129 |
| A lazily-memoized module-level singleton needs a test reset hook | dev/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 rule | dev/guidelines/frontend/page-architecture.md | #10111 |
Component design and code style (.agents/rules/ — edits to existing rules, no new files)
| Convention | Lives in | Source |
|---|---|---|
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
| Convention | Lives in | Source |
|---|---|---|
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 separately | dev/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-it | dev/guidelines/documentation.md For Internal Docs | the harvests themselves |
No file.py:line citations in internal docs; measurements go in as relative comparisons | dev/guidelines/documentation.md | #10038, #10108 |
| Verify identifier/metric/config-default claims against the diff before writing them into fragments, PR text, or ADRs | root 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 background | docs/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 suggestedstable, discussed with @polmichel):git-workflow.mdhas no docs-target-stable rule, the lessons were verified againstdevelop's code, and several describe modules that don't exist onstable. If internal-docs-to-stable should be policy, that's agit-workflow.mdrule to add first. - Dropped, not restored: four develop-only lessons from a brief
stableretarget (diff-tree node sets #10014, merge-recompute invariant #9845,get_query_arrows()#10053-cluster,ComputedAttributedrift 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.pymissing the documentedr.status ASCtiebreaker; develop's dashboards carrying 42 undefined-$datasourcereferences (#10153 fixed them only onrelease-1.11);changelog/models.py'sset_value_previousbypassing the masking validator; #10133's broker-durability lessons parked until the Redis driver merges; thestable/developruffBLEdivergence. - 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/Sequencedoc section became the rule against the pattern, the extract skill's error-handling route repointed toexceptions.md,backend/AGENTS.md's list made contiguous, the retry-trigger wording completed, the test examples made reproducible and actually-isolating,vi.resetAllMocksoverclearAllMocks, 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.
| File | Lines | Range |
|---|---|---|
dev/knowledge/backend/query-pattern.md | 490 | 200–400 — the ## Internals split is the flagged next change |
dev/guidelines/backend/python.md | 414 | 100–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.md | 398 | 200–400 |
dev/guidelines/backend/testing.md | 393 | 100–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