Agent Notes

Read the Agent Note rules before acting. Agent Notes preserve revisitable decisions; they do not replace current code, reference docs, issues, or PR discussion.

Classify the change

Every human-authored PR declares an Agent Note or an explicit N/A reason. Automation-authored PRs (repository workflows and Dependabot) are exempt from this metadata requirement, not from normal validation.

The class names the decision's subject; it does not force every note to start as proposed. Choose the initial lifecycle from whether the target needs human agreement before implementation and whether the decision has already shipped.

• Use N/A for a local or mechanical edit that restores an existing contract without a durable tradeoff.
• Write an implemented bug-fix note in the same PR when the repair changes failure, compatibility, security, concurrency, atomicity, lifecycle, or another choice likely to be reversed without its root cause.
• A small, completed testing or other durable decision that does not meet the Spec-first threshold may enter its owning class as implemented.
• Start substantial feature, architecture, process, and simplification work with a proposed Spec.
• Start any class as proposed when behavior, ownership, ACs, alternatives, or risks need human agreement before implementation.

Check the active tree first

Search by domain terms, mechanism names, paths, and rejected alternatives. Classify the result as new, same owner, partial supersession, or full supersession. Update the existing owner when possible. Partial supersessions stay active and cross-linked. Full supersession must preserve every unique rationale, alternative, consequence, and verification fact; deleting an old note requires explicit human approval.