Skip to content

docs: make capturing lessons learned an explicit done gate#262

Merged
bkrabach merged 1 commit into
mainfrom
docs/per-repo-conventions-capture-lessons
Jun 27, 2026
Merged

docs: make capturing lessons learned an explicit done gate#262
bkrabach merged 1 commit into
mainfrom
docs/per-repo-conventions-capture-lessons

Conversation

@bkrabach

Copy link
Copy Markdown
Collaborator

Summary

This change makes "capturing lessons learned back into per-repo convention files" an explicit part of the "done" requirements for any work session, closing a gap where important lessons surfaced during development were never saved back into the conventions.

Motivation

Today, agents and developers discover footguns, refine invariants, and reach team agreements about how work should be done — but these lessons often evaporate at session end rather than becoming part of the collective knowledge encoded in AGENTS.md, PRINCIPLES.md, PR templates, and KNOWN_ISSUES.md. This means the next session re-arms the same footguns and re-litigates the same design questions.

What Changed

In docs/PER_REPO_CONVENTIONS.md:

  1. New lifecycle gate — Added "Capturing what you learned" to the "Honor what you read" list (the list of obligations that close a work session), making lesson-capture an explicit done criterion alongside PR templates, gate execution, and deferral logging.

  2. Dual capture discipline — Requires capturing lessons both inline as the lesson lands and as a session-end sweep before declaring work done, providing belts-and-suspenders protection against lost context. Uses the same offer-and-confirm discipline as deferral to prevent becoming a dumping ground.

  3. Awareness-boundary routing — Adds an enforcement rule: lessons may only be written into a repo when that repo is allowed to know what the lesson describes. Anchors to amplifier's REPOSITORY_RULES.md as the canonical authority for repo awareness boundaries, preventing lessons about dependents from leaking into agnostic upstream repos.

  4. Consistency updates — Refreshes owner guidance, cross-references, and TL;DR to reflect the new gate and cross-link to the routing rule.

Design Rationale

  • Belts and suspenders: Inline capture catches lessons hot; session-end sweep catches ones that fell out of context.
  • No checklist for what's worthy: Trust the model's judgment. A footgun, a fixed invariant, or an agreed design decision is worth capturing; passing TODO noise is not.
  • Routing defers to existing authority: Rather than re-derive repo awareness rules, anchor to the existing REPOSITORY_RULES.md table (Repo-Type → Awareness-Rule), so lessons respect the same boundaries as all other cross-repo knowledge.

This prevents a category of silent regressions: sessions that pass all gates, tests, and PRs but leave the next session unprotected against the same class of bugs, or re-discovering the same design constraints.

…rkflows

Add 'Capturing what you learned' to the Honor-what-you-read lifecycle list,
making it an explicit obligation to save lessons (footguns, fixed invariants,
agreed decisions) back into the appropriate repo convention files
(AGENTS.md, PRINCIPLES.md, PR templates, KNOWN_ISSUES.md) both inline as
lessons land and as a session-end sweep before declaring work done. Uses the
same offer-and-confirm discipline as deferral to prevent it becoming a
dumping ground.

Also adds awareness-boundary routing: lessons may only be written to files
naming other repos when allowed by repository dependency rules. Anchors to
amplifier's REPOSITORY_RULES.md as the canonical authority for awareness
boundaries, preventing lessons from leaking into agnostic repos that should
remain unaware of their dependents.

Updates owner guidance, cross-references, and TL;DR for consistency.

Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
@bkrabach bkrabach merged commit 491d312 into main Jun 27, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant