docs: a learning must generalize past the change that taught it (1.0.2)#25
Merged
Conversation
Refine the protocol's definition of a learning so it captures only guidance that continually improves the development lifecycle, not one-off corrections specific to a single feature. The old section 6 text blocked two failure modes - a learning isn't a feature description and you shouldn't manufacture one - but never required a learning to generalize. A real correction that applied only to the feature that produced it passed every test and got logged, diluting the store. Add the missing transferability axis: a learning must outlive the change that taught it. - Rewrite the section 6 definition and tighten the section 3 feedback-doc Learning field. - Capture the friction in feedback/0014 and log the learning itself (it extends feedback/0005 with the generality axis). - Bump to 1.0.2 and refresh README token figures. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mattmaynes
commented
Jun 27, 2026
mattmaynes
left a comment
mattmaynes
left a comment
Collaborator
Author
There was a problem hiding this comment.
📐 Spectra Architect - review of the learning-generality refinement.
The new §6 definition cleanly adds the transferability axis on top of feedback/0005's description-vs-lesson axis, the learnings.md entry correctly cites 0005 as the prior art it extends, and the dogfooded entry itself clears the new bar (it is a meta-rule about Reflect, general to every future change). The feedback -> learning -> applied data-flow stays sound. Two internal-consistency nits below; no major/blocker findings.
Per architect persona review on PR #25: - Section 6 gate "No feedback and no recurring rule" read as a conjunction of absences, so feedback without a generalizing rule would still pass. Make the two requirements independent gates: "No feedback, no learning; nothing that generalizes, no learning." - Section 3 Learning field claimed it unconditionally feeds learnings.md, contradicting section 6's diversion of feature-specific lessons. Make the routing conditional on generalizing. Refresh README token figures. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.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
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.
What
Refines the Spectra protocol's definition of a learning so
overview/learnings.mdcollects only guidance that continually improves the development lifecycle - not one-off corrections that apply to a single feature and won't recur.Why
The old section 6 text guarded two failure modes (a learning isn't a feature description; don't manufacture one) but never required a learning to generalize. A genuine "do it differently" correction that only ever applied to the feature that produced it passed every existing test and got logged - diluting the lessons that actually transfer. The missing axis was transferability.
Changes
spectra/protocol.mdsection 6 - rewritten definition: a learning is a rule you'd apply differently next time that outlives the change that taught it; a lesson specific to the feature you just shipped belongs infeatures.md/architecture.md.spectra/protocol.mdsection 3 - tightened the feedback-doc Learning field to "the general rule to apply next time, not just this one fix."docs/feedback/0014-learnings-must-generalize.md- captures the friction.docs/overview/learnings.md- logs the learning itself (extendsfeedback/0005with the generality axis) and reframes the header.docs/spectra/protocol.mdis a symlink to the shippable source, so both update together.Testing
./test.shpasses (token figures refreshed viascripts/token-report.sh --write).🤖 Generated with Claude Code