DOC-6792 add agent experience-notes system: /reflect capture + /finalize distiller

[andy-stark-redis]

Note: even if you think this is looking OK, it's probably best not to start using it yet. I'll test run it on a real doc PR before recommending and documenting it :-)

What this is

A skill-based system for recording agent experience notes — the lived reasoning behind a
change (what was learned, what was rejected, what a future editor must not break) — in git
itself rather than a standalone lessons file. Body prose carries the reflection (for humans
and the semantic history bot); git trailers carry atomic, queryable facts.

It chooses our own thin vocabulary over Lore
(arXiv:2603.15566): Lore's trailer mechanism is sound, but its CLI/vocabulary are young, and
it has no field for process lessons — which is our Learned: addition.

The three-tier pipeline

/reflect          →  WIP commit messages         [episodic, provisional, disposable]
PR review + bots  →  PR comments                 [external critique]
        ↓  /finalize, just before squash
/finalize         →  squash commit message        [durable, location-reachable]
        ↓  fork
promotion         →  learning skills / memory      [cross-cutting, always-loaded]

• .claude/skills/reflect/ — captures a note into a commit message (or a marked PR comment
  if already pushed). A worth-it gate keeps it silent on mechanical commits.
• .claude/skills/finalize/ — reconciles the notes across a PR's commits and the review
  feedback into the one commit that survives the squash; proposes promoting cross-cutting
  lessons to learning skills/memory. Prepares the message + gh pr merge command; does not
  merge.
• .claude/skills/_shared/commit-trailers.md — the single source of truth for the trailer
  vocabulary, subject convention, format rules, and the author-note marker. Both skills
  reference it so capture and distillation can't drift.

Design notes for reviewers

• Capture lands in commit messages, not PR comments — no PR exists at the first commit, the
  note binds to its diff, and author reflection stays distinct from reviewer critique.
• Core vocabulary: Constraint / Rejected / Directive / Learned; situational
  Reversibility / Gaps / Ticket / Recheck. A field earns a slot only if reading it
  would change a future agent's decision.
• /finalize reconciles to the end state, it doesn't concatenate — notes the PR later
  overturned are dropped, not frozen onto main. It reads the arc oldest-first (--reverse).
• Squash mechanics: the repo squashes via COMMIT_MESSAGES, so /finalize overrides the
  body explicitly with gh pr merge --squash --body-file rather than relying on the default.

Dogfooded on its own commits

Every commit here uses the convention on itself; the worth-it gate fired yes on the
substantive commits and no on a doc tweak. /finalize has been dry-run against this PR's
own arc and correctly dropped discharged directives and refined an overturned Rejected.
Several commits are Bugbot fixes — notably a chain of cross-skill contract bugs that surfaced
only once both skills existed.

Not done / follow-ups

• Not yet exercised on a real content PR — validated only against this self-referential PR
  about the skills themselves. First non-self test is the next docs change that runs the
  pipeline.
• No automated merge-time backstop — /finalize is human-triggered by design; an
  optional GitHub Action backstop is possible later (it would also need --body-file).
• Long-term, these may move into the docs: plugin beside assess-comments.

Ticket: DOC-6792

---

Note

Low Risk
Documentation-only Claude skill definitions; no application, CI, or merge behavior changes until humans invoke the skills.

Overview
Adds a three-tier pipeline for persisting agent reasoning in git: /reflect captures provisional notes in WIP commit bodies and trailers; /finalize reconciles those notes plus PR review into the squash commit and hands off gh pr merge --squash --body-file (it does not merge).

Introduces .claude/skills/_shared/commit-trailers.md as the single source for trailer vocabulary (Constraint, Rejected, Directive, Learned, etc.), DOC-XXXX subject rules, parseable trailer blocks, and the <!-- reflect-note --> marker so author notes in PR comments are not treated as reviewer critique.

/finalize is defined to reconcile to end state (oldest-first git log --reverse, drop overturned WIP notes) rather than concatenate WIP messages—important because the repo’s squash default is COMMIT_MESSAGES. Both skills split location-bound notes (commit trailers) from cross-cutting lessons (proposed promotion to learning skills/memory).

^{Reviewed by Cursor Bugbot for commit 1eeb2ff. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

DOC-6792

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7b23623. Configure here.}

[dwdougherty]

Interesting. No notes.

[andy-stark-redis]

Interesting. No notes.

@dwdougherty I'm not sure if you mean this is good or bad? (I'm guessing it's at least tolerable since you approved the PR.) Anyway, thanks for the review :-)

[dwdougherty]

Interesting. No notes.

@dwdougherty I'm not sure if you mean this is good or bad? (I'm guessing it's at least tolerable since you approved the PR.) Anyway, thanks for the review :-)

Certainly not bad. I guess "cool" would have been a better word. I think I wrote that when I was in the middle of fisticuffs with Claude. 🤣