Conventions and learnings: two-type capture for agent-applied preferences

Context and Problem Statement

0005-personal-domain-zen-captures-processes ruled out preference docs after a single restaurant note got applied by agents as a hard filter on every suggestion. That was a cold-start failure: one sample treated as a rule. The fix was to capture decision processes instead, which carry more information at n=1 and don’t collapse the search space.

Two things have changed since April. Agents now read the vault at generation time, and the cost of having no home for corrections showed up: the same dark-mode fix for HTML artifacts has been re-explained across four or more chats, and a wallpaper session (2026-09-19 Quant Wallpaper Session and Design Vocabulary) took fourteen iterations partly because nothing carried between attempts. Meanwhile Writing Conventions has been a working preference doc since 2026-09-06 without anyone noticing it contradicted 0005.

The question is not whether to capture preferences but how to capture them so a single sample can’t steer every future session, while a repeated correction stops needing to be repeated.

Considered Options

• Keep 0005 as written: processes only, no preference docs.
• Preferences with a confidence ladder per line (RFC 2119 MUST/SHOULD/MAY, or hypothesis/prior/rule) and agent behavior keyed to the level.
• Two types split by author: conventions (human-authored, agent-applied) and learnings (agent-appended, dated, cite their source), with promotion on recurrence.

Decision Outcome

Chosen option: “Two types split by author”, because it is what the widely used systems converge on and it needs the least machinery.

Conventions are human-written and human-reviewed. Rules are imperatives an agent applies silently. Defaults are written as Prefer X over Y: the agent applies X and states a one-line reason when it chooses Y. One conventions doc per output family in Atlas/References/ (Writing Conventions, Visual Conventions to follow), kept under about 30 lines because shorter instruction files perform better.

Learnings are agent-appended in the session where a correction happens: dated, one line, pointing at the journal entry or session. Corrections given, approaches confirmed, alternatives rejected. An agent consults learnings but does not apply them silently; a learning that bears on the task is surfaced as an option.

Placement

Placement follows the vault’s modes (0006-mode-based-top-level-structure): conventions are knowledge an agent applies, so they are Atlas; learnings are dated and append-only and exist to be reflected on, so they are Chronicles. Keeping learnings as an edit log inside a References doc mixed the two modes and was tolerable only while the log was short.

• Conventions: Atlas/References/Conventions/<Family> Conventions.md. A subfolder on the same precedent as References/ADR/ and References/Devices/: a set of same-shaped notes with its own Templater scaffold (rules, prefer-X-over-Y defaults, process, link to the family’s learnings file). Frontmatter: date, tags: [reference, <family>].
• Learnings: Chronicles/Learnings/<Family>.md. One file per output family, two sections.
  • ## Learnings: agent-appended, dated lines, newest at the bottom. Line shape: YYYY-MM-DD · correction | confirmation | rejection · what happened · [[source journal entry]]. Cap around 100 lines; a reflection prunes lines that never recurred.
  • ## Changelog: every edit to the conventions doc gets one line here, whatever its origin: YYYY-MM-DD · added | changed | removed | promoted | demoted · the rule · reason. Promoted and demoted lines link the learning lines that justified them; added and changed lines cite an ADR, prior art, an environment constraint, or “direct” when it was a judgment call with no source. Promoted learnings move here from Learnings rather than being deleted. Git carries the diff; this line carries the why.
• Conventions docs hold current rules only. No changelog, no history, nothing that isn’t a rule or a default. History lives in ## Changelog and in git.
• Retrieval: before producing output in a family, an agent reads that family’s conventions doc and the ## Learnings section of its learnings file. It does not read ## Changelog; a removed or reworded rule in a changelog is a trap for an agent, not context. If skipping a section proves unreliable in practice, ## Changelog moves to its own file per family (<Family> Changelog.md) so the read path is whole files only. Follow-up, not decided here.
• Map of Content: none yet. The folder listing plus the README row covers “what exists.” A MoC is warranted when a second principle note exists (a reason like “don’t ship signals of low perceived quality” that justifies rules in more than one family), because relating principles to rules across families is what a folder can’t show.

Considered and deferred: one learning per note in Inbox/ (the vault’s own seedling ladder, but Inbox stops emptying since learnings wait to recur); a learning fileClass with a Base (queryable status and audit trail, at the cost of a file per correction; the migration is mechanical if lines are already typed and dated, so it stays available).

Existing notes sort into the new shape as follows. Writing Conventions moves into the Conventions subfolder; its one “Created” entry is a Changelog line. Professional Email Tone stays as the email medium under writing; its four dated draft-vs-sent entries are learnings and move to Chronicles/Learnings/Writing.md, with a link left behind. SigNoz Dashboard Design Guide is already a conventions doc for a fourth family and moves to Dashboard Conventions.md; the three journal entries it links become its first Learnings lines. A Visual Conventions doc is created new, holding only what is shared across visual output, and links down to the dashboard doc for dashboard-specific traps. Hostname, Zotero, and the CSS and design knowledge notes are references or knowledge, not rules an agent applies to output, and stay where they are.

Promotion is the one human step. A reflection (README § Chronicles) reads the learnings and moves what recurs into conventions. Default threshold: the same correction on three separate dates. A correction that contradicts a convention is logged as a learning; if it recurs, the convention is edited or demoted to a prefer-X-over-Y default.

0005’s rule survives as the zero-evidence case: with no learnings yet, write the process. Its status becomes superseded because this record restates the rule with its scope.

Grounding

• Claude Code splits CLAUDE.md (you write, “instructions and rules”) from auto memory (Claude writes, “learnings and patterns”, typed user/feedback/project/reference). No confidence field; recurrence and dates do that job. Docs.
• Generative Agents (Park et al., 2023): append-only observation stream, periodic reflection that writes higher-level insights back as new memories citing their evidence. Paper.
• Kolb’s experiential learning cycle names the loop the vault already runs: journal (concrete experience), reflection (reflective observation), notes and conventions (abstract conceptualization), the next session (active experimentation). Overview.
• RFC 2119 SHOULD is the prefer-X-over-Y contract in standards language: recommended, deviation allowed with understood implications. RFC 2119.

Consequences

• Good, because corrections have a home and a path to becoming rules without being re-explained.
• Good, because conventions stay short and human-owned; nothing an agent writes changes behavior until a person promotes it.
• Good, because the April failure can’t recur: a single learning is surfaced, never applied.
• Bad, because learnings accumulate and need pruning or the edit log rots.
• Bad, because “three dates” is a guess until a few reflection passes test it.
• Bad, because the wiring (memory preferences, CLAUDE.md, skills pointing at the conventions docs) is separate work, tracked in Writing Conventions Rollout.
• Bad, because two new folders (Atlas/References/Conventions/, Chronicles/Learnings/) and a template are structure added for two families; justified by the ADR/ precedent but thin until a third family appears.

Pros and Cons of the Options

Keep 0005 as written

• Good, because it is simple and proven safe against over-indexing.
• Bad, because repeated corrections have nowhere to go, and Writing Conventions already violates it.

Confidence ladder per line

• Good, because agent behavior is explicit per line.
• Bad, because no widely used system does this; recurrence plus dates does the same job with less to maintain, and a per-line level is one more thing to get wrong.

Two types split by author

• Good, because it matches Claude Code, the agent-memory literature, and the existing writing doc.
• Bad, because promotion needs a reflection habit; without it learnings never graduate.