- name
- agent-notes
- description
- Use when deciding whether a Cherry Studio change needs an Agent Note, authoring or reviewing a Spec, recording a durable bug-fix decision, moving a note between proposed/implemented/rejected, or checking supersession and stacked Spec approval.
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/Afor a local or mechanical edit that restores an existing contract without a durable tradeoff. - Write an implemented
bug-fixnote 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.
There is no archived/ lifecycle yet. Do not archive by age, merge status, moved code, or stale wording. Keep current owners factual; keep fully superseded notes active and cross-linked until a separately approved archive design provides active-first search, successor discovery, and matching gates.
Spec-first stack
- Create the bottom Spec branch and proposed bilingual note.
- Give observable acceptance criteria contiguous
ACIDs and a verification owner.