AGENTS.md@learnings git:20260922.a4fc9b1A

Immutable. This exact content is served forever at /api/v1/blob/3eefe2f07fe6b037.

# Learning-engine guidance

This file applies under `learnings/` and to `scripts/engine/` work. Load the
`learning-loop` skill for consolidation, absorption, refining, experiments, or
retention maintenance.

## Capture without interrupting builds

- Hooks silently queue corrections/errors and archive session transcripts.
- Do not stop implementation to write a learning after every event. At a
  natural milestone, batch meaningful flags into the schema in `README.md` and
  discard context-free noise.
- A retro is useful only when it carries a real signal; clean per-skill score
  lines are not mandatory.
- Project-local facts belong in the owning app/site documentation, not in the
  cross-project learning corpus.

## Promotion and absorption

- Queue flags are pointers, not knowledge. Promote only when the transcript
  establishes expected behavior, actual behavior, and a skill or `[none]`.
- Only `status: ready` observations can be absorbed. Preserve tentative,
  rejected, and absorbed entries as the dedup/audit trail.
- Consolidation may change `learnings/`, observations, evidence, and eval
  sidecars; it never changes `skills/`.
- During an app build, capture and continue. Absorb between builds unless the
  maintainer explicitly requests a skill change in the current conversation.
- Automated or unrequested absorption ends in a PR. A maintainer-authorized
  direct-main edit still needs a concrete diff, evidence, and proportional
  validation, but live skills do not use versions or changelogs.

## Learning retention

Dated learnings are gitignored local staging, not a durable corpus. Keep one
until its entries are distilled, then delete it — the knowledge worth having
belongs in the owning skill, in `references/` when it is conditional detail,
a dead end, or a platform-specific value. `observations/`, the schema, and
`SOURCES.md` stay tracked.

Never hand-delete a dated learning. Run
`uv run scripts/engine/prune_transcripts.py --dry-run --learnings`; a file is
eligible only when every entry it defines is cited by a terminal observation.
An entry no observation cites keeps its file indefinitely, which is the point:
undistilled capture must outlive any cleanup.

## Transcript retention

Transcripts are evidence, never prompt context. Keep a transcript while queue
flags or tentative/ready observations depend on it. After linked observations
are absorbed/rejected and the change lands, run the retention tool to delete
the raw transcript. Unreferenced transcripts expire after 14 days.