docs(lessons): distil retrospectives#427
Merged
Merged
Conversation
Replace the lessons.md placeholder with 11 lessons distilled from the two existing retrospectives (Phase 28 trusted-proxy and Phase 29 pdm-to-uv migration). Each bullet links back to its source retrospective so readers can trace the lesson to the incident that produced it. The tk_ agent-key short-circuit invariant from Phase 28 is flagged in the PR body as a tech-stack.md promotion candidate but not promoted in this PR — promotion is a manual edit per the SDD constitution. Signed-off-by: Vladimir Gorej <vladimir@jentic.com>
|
🎉 This PR is included in version 0.13.2 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
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
1 participant
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
_(no lessons captured yet)_placeholder inspecs/lessons.mdwith 11 lesson bullets distilled from the two retrospectives currently in the repo (Phase 28 trusted-proxy, Phase 29 pdm→uv).— captured from \specs/-/retrospective.md`` so future spec authors can trace any lesson back to the incident that produced it./sdd-new-specand/sdd-new-phaseautomatically loadlessons.md, so these lessons reach the next spec author without further action.Promotion candidate for
specs/tech-stack.md(manual follow-up)Phase 28's retrospective explicitly marked one lesson as
## Promotion candidate: yes— a load-bearing invariant of the two-actor authentication boundary:Suggested home: extend the existing "Authentication model (two actors)" bullet under
## Constraints and Conventionsinspecs/tech-stack.mdso every future auth-chain change inherits the ordering rule. Promotion is a hand edit per.claude/rules/sdd-constitution.md; deliberately not done in this PR.Test plan
git diff origin/main -- specs/lessons.md— confirm onlyspecs/lessons.mdis touched and the placeholder is replaced (not appended around).specs/2026-05-12-trusted-proxy-forwarded-identity/retrospective.md,specs/2026-05-20-migrate-pdm-to-uv/retrospective.md) to confirm they faithfully reflect the source.grep -c '^- ' specs/lessons.md— expect 11.