Curated, generalized lessons that recur across projects — the durable memory of the engineering system.
Two tiers, kept distinct:
- Project-local lessons live in each project's
docs/agent-lessons/, written during/project-closeoutby mining that project's local-review findings. - Generalized lessons live here. When a lesson family recurs across projects (e.g. "new E2E spec ⇒ register it in the CI matrix", dependabot triage), it's rewritten stack-agnostically and promoted here.
/project-closeout ends with: if a mined lesson generalizes, open a PR against
engsys/lessons-library/. That's the feedback loop that keeps engsys the source
of truth instead of a fork point.
One lesson per file. Keep them LLM-optimized and trigger-first:
# <short title>
**Trigger:** the symptom that should make you recall this.
**Failure mode:** what goes wrong and why.
**Correct behavior:** the checklist / the fix.
**Check:** a quick diagnostic before/after.
**Seen in:** keep it generalized — e.g. "recurring across projects."This library is published publicly (npm + GitHub). Generalize before promoting: never include private project/repo/company names, secrets, internal hosts, or proprietary specifics in a lesson. The pattern is what's portable, not the particulars.
A future installer option may seed a project's docs/agent-lessons/ with the
lessons relevant to its chosen stack. For now, promotion is manual via PR.
- verify-ground-truth-not-reports — check real state, not the narration.
- independent-objective-review-gate — fresh reviewer re-runs the gate, binary verdict.
- tests-can-assert-the-bug — a green test that contradicts a root cause is a suspect.
- prove-causation-before-acting — observe at the deciding boundary before fixing.
- re-read-state-before-acting — re-read at the moment you act, not at session start.
- gate-changes-on-measurement-not-vibes — eval/golden-set, not intuition.
- shift-correctness-left-and-distrust-false-greens — pre-push checks; a gate that didn't run is a false green.
- claim-then-act-for-irreversible-ops — stamp the claim atomically, then execute.
- async-callbacks-verify-liveness — confirm the target is still current before mutating it.
- enforce-your-guarantee-at-your-boundary — redact/sanitize/audit/authorize where you emit.
- keep-an-immutable-source-of-truth — raw immutable; downstream is a replayable transform.
- model-identity-with-stable-ids-and-provenance — join on stable ids; carry source+timestamp.
- read-layer-tolerates-unbackfilled-rows — handle legacy rows during the backfill window.
- change-isnt-done-until-every-surface-updated — update every rippled surface in the same PR.
- operator-choices-are-first-class — track operator choices; copy criteria verbatim.
- co-commit-entangled-work — co-commit file-sharing issues; skip already-merged commits on rebase.
- stray-control-bytes-hide-changes — control bytes turn files binary and silence review.
- long-agent-runs-checkpoint-not-poll — checkpoint into short runs; end agents at PR-open.
- deploy-by-digest-and-verify-the-running-revision — immutable digest; verify the active revision.
- iac-first-no-console-changes — version-controlled IaC with state and drift detection.
- worktrees-need-bootstrap-from-origin-main — branch off origin/main; bootstrap; absolute paths.
- shell-safety-pipefail-and-validate-before-teardown — pipefail; validate the risky step before teardown.
- prefer-tool-enforced-structured-output — schema/tool-enforced output over prompt-policed format.
- dependabot-triage-playbook — 6-phase order for clearing a Dependabot pile.