docs: make capturing lessons learned an explicit done gate#262
Merged
Conversation
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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: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.
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.
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.mdas the canonical authority for repo awareness boundaries, preventing lessons about dependents from leaking into agnostic upstream repos.Consistency updates — Refreshes owner guidance, cross-references, and TL;DR to reflect the new gate and cross-link to the routing rule.
Design Rationale
REPOSITORY_RULES.mdtable (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.