Strategy
Defines intent.
System 06 · Evidence, adaptation & improvement
The Learning Engine
The evidence-to-improvement system that turns outcomes, failures, measurements, human experience, and reusable discoveries into better knowledge, platforms, playbooks, governance, and agent behavior.
Knowledge
Establishes truth.
Execution
Delivers and proves.
Platform
Preserves reuse.
Governance
Controls authority.
Learning
Changes future behavior.
01 · Mandate
Close the loop from evidence to verified improvement
Learning is complete only when the correct authoritative system changes and later evidence shows that future behavior improved.
Learning is an operating capability
Execution produces evidence. Experience reveals whether the result works for people. Learning explains what should change. Governance authorizes consequential adoption.
The engine routes approved improvements back into Strategy, Knowledge, Execution, Platform, and Governance.
Execution produces evidence.
Experience reveals human truth.
Learning explains the difference.
Governance authorizes change.
The operating system absorbs improvement.
A lesson is not learned when it is documented. It is learned when future behavior changes—and the change is verified.
02 · Responsibilities
Twelve questions make a learning cycle actionable
The engine distinguishes observed facts from supported conclusions and connects every improvement to an owner, destination, and verification measure.
Objective event, observation, result, or measurement.
Referenced requirement, target, hypothesis, or assumption.
Supported cause or clearly unresolved hypothesis.
Reproduction evidence and confidence level.
Scope across product, platform, process, and organization.
Corrective or amplifying improvement proposal.
Strategy, Knowledge, Execution, Platform, or Governance.
Named owner of the affected artifact or policy.
Specification, test, playbook, capability, or rule.
Follow-up measure or recurrence test.
Revalidation event, target, or review date.
Better quality, speed, experience, or reuse.
Negative learning
Defects, failed assumptions, delays, regressions, ambiguity, and escaped risk.
Positive learning
Successful patterns, reusable solutions, strong experience feedback, and efficient agent behavior.
03 · Delivery phase
Experience and learning belong inside delivery
They are required stages—not optional retrospectives after the project has already moved on.
1Plan
2Specify
3Build
4Verify
5Experience
6Learn
7Improve
8Repeat
Human feedback returns to OpenSpec Explore and Propose before the next Apply cycle begins.
04 · Inputs
Every system emits learning signals
The engine combines technical evidence, operational behavior, contributor experience, and human perception without flattening them into one undifferentiated data stream.
Outcome performance and invalidated assumptions.
Ambiguities, contradictions, and missing edge cases.
Defects, rework, blockers, and better techniques.
Adoption, duplication, compatibility, and cost.
Approval delays, escapes, and repeated exceptions.
Tests, regressions, coverage gaps, and measurements.
Feel, delight, frustration, and accessibility.
Build reliability, reproducibility, and field faults.
Onboarding friction and unclear ownership.
Context failures, tool errors, and reusable patterns.
Preserve the boundary: “Pause felt delayed” is an observation. “Audio synchronization caused perceived latency” remains a hypothesis until evidence supports it.
05 · Learning package
Connect the signal, conclusion, decision, and effect
A meaningful learning cycle produces a traceable package from baseline through effectiveness review.
| Artifact | Purpose |
|---|---|
| Learning Brief | Defines event, scope, importance, and owners. |
| Expectation Baseline | Records what was expected and why. |
| Evidence Bundle | Preserves tests, measurements, feedback, traces, and observations. |
| Finding Record | States supported conclusion and confidence. |
| Causal Analysis | Explains contributing mechanisms without defaulting to blame. |
| Learning Classification | Identifies type, scope, severity, and destination. |
| Improvement Proposal | Defines exactly what should change. |
| Adoption Decision | Approves, rejects, defers, or limits the lesson. |
| Change Links | Connects learning to authoritative system changes. |
| Verification Plan | Defines how institutionalization will be proved. |
| Effectiveness Review | Measures whether the improvement worked. |
| Supersession Record | Replaces learning invalidated by later evidence. |
06 · Record contract
Make the lesson machine-readable and human-reviewable
The contract binds a specific build and target to its expectation, observation, finding, scope, owners, proposed improvements, and revalidation trigger.
LEARN-LIFECYCLE-007
Pause meets the state-transition requirement but feels late because audio response is not synchronized with visual feedback.
- Technical and human evidence remain distinct
- Excluded causes are explicit
- Impact is routed across systems
- Success measures are defined before adoption
learning_id: LEARN-LIFECYCLE-007
status: proposed
classification: cross-system
confidence: high
source:
change_id: CHANGE-GAME-LIFECYCLE-001
build: rp2350-game-platform-0.5.0
target: feather-rp2350-hstx-rev-a
expectation:
transition_latency_frames: 1
perceived_response: immediate
observation:
state_transition_frames: 1
audio_response_ms: 27
participants_reporting_delay: 4_of_5
finding:
statement: delayed audio caused perceived latency
excluded_causes: [input-loss, state-corruption]
proposed_improvements:
- add cross-modal response criteria
- validate audio-visual synchronization on target
owners:
learning_owner: qa-lead
adoption_owner: chief-architect
verification:
audio_latency_ms: 20
perceived_immediate_rate: 0.8
revalidate_on: platform-audio-architecture-change07 · Classification
Classify before routing
One finding may produce several improvements, but every improvement has one accountable destination owner.
| Classification | Meaning | Typical destination |
|---|---|---|
| Product learning | Experience differs from expectation | Strategy or product knowledge |
| Requirement learning | Specification was incomplete or ambiguous | Knowledge |
| Technical learning | Implementation behavior or constraint emerged | Knowledge or Execution |
| Hardware learning | Target behavior differs from assumption | Hardware knowledge + Platform |
| Platform learning | Reusable boundary or compatibility issue emerged | Platform |
| Process learning | Workflow created delay, waste, or missed evidence | Execution playbooks |
| Governance learning | Authority, gate, or risk policy was ineffective | Governance |
| Agent learning | Instructions, context, tools, or decomposition should change | Agent configuration + evaluation |
| Quality learning | Acceptance or validation was insufficient | Knowledge + QA playbooks |
| Strategic learning | Outcome or investment assumption is invalid | Strategy |
| Positive pattern | A successful technique may generalize | Playbook or Platform |
| Local anomaly | Finding is real but not generalizable | Product-local record |
08 · Evidence hierarchy
Scale generalization with evidence strength
Qualitative experience remains meaningful; it is captured systematically without pretending human perception is purely technical telemetry.
E0 · Anecdote
Single impression
Create an observation; do not generalize.
E1 · Reproduced
Repeated behavior
Confirm a local finding.
E2 · Measured
Instrumented evidence
Support corrective action.
E3 · Comparative
Baseline vs change
Support causal confidence.
E4 · Multi-context
Across consumers
Support platform adoption.
E5 · Longitudinal
Effective over time
Confirm institutional learning.
For RP2350: simulation suggests; target-board measurement confirms hardware behavior; human playtesting confirms experience; multiple consumers or a reference harness support generalization.
09 · Lifecycle
Move from signal to verified institutional change
“Documented” is deliberately not a terminal state.
Observed
Qualified
Investigating
Proposed
Adopted
Institutionalized
Inconclusive
Rejected
Deferred
Verified
Superseded
Verified means later evidence demonstrates that the adopted improvement changed behavior and achieved its intended result.
10 · Routing
Learning is a routing engine—not another backlog
The nature of the finding determines the authoritative system, artifact, and owner that must change.
| Finding | Required action |
|---|---|
| Desired outcome was wrong | Amend Strategy |
| Requirement was unclear | Update Knowledge |
| Work package was poorly bounded | Improve Execution schema or playbook |
| Reusable mechanism emerged | Propose Platform promotion |
| Platform contract failed consumers | Revise Platform through governed change |
| Approval policy caused delay | Update Governance |
| Human experience contradicted technical success | Update experience requirements and tests |
| Agent repeatedly misunderstood an artifact | Improve instructions, context assembly, or evaluation |
| Hardware behaved unexpectedly | Revise hardware assumptions with target evidence |
| Defect escaped validation | Add regression test and improve validation |
| Technique reduced effort | Standardize through a playbook |
| Product behavior was mistaken for reuse | Retain locally and document the boundary |
11 · Adoption Gate
Evidence does not rewrite authority on its own
The Learning Adoption Gate determines whether a proposed conclusion is ready to change specifications, capabilities, playbooks, policies, or strategy.
Minimum adoption contract
Clear expectation + observationEvidence fits impactCause or uncertainty statedScope definedAffected artifacts identifiedAdoption owner namedMigration effects knownVerification plan existsNo higher-order conflictHuman authority approves consequence
gate: learning-adoption
decision: approved
risk_tier: 2
learning:
id: LEARN-LIFECYCLE-007
version: 1.0
confidence: high
approved_conclusion:
statement: responsiveness includes synchronized feedback
authorized_changes:
knowledge: [QREQ-LIFECYCLE-004]
platform: [CAP-GAME-LIFECYCLE@next-minor]
playbooks: [validate-on-target, experience-review]
excluded:
- change lifecycle state model
- promote product-specific audio policy
verification:
target_build: rp2350-game-platform-0.6.0
required_evidence: [board-latency, harness, human-review]
approved_by: [architect, steward, qa, product]12 · Human + AI
AI accelerates learning; humans own consequential meaning
Pattern detection and structured synthesis can be automated. Strategic meaning, generalization, experiential interpretation, and risk acceptance remain human responsibilities.
AI contribution
- Detect repeated patterns
- Synthesize evidence
- Generate causal hypotheses
- Recommend routing
- Draft improvements
- Evaluate agent runs
- Compare outcomes over time
Human responsibility
- Decide which patterns matter
- Challenge unsupported conclusions
- Apply domain and experiential judgment
- Confirm accountability
- Approve authoritative changes
- Define acceptable agent behavior
- Own risk and consequential success
AI generates; humans govern. Learning never bypasses the authority of the system it seeks to change.
13 · Agent learning
Improve agents through governed, versioned artifacts
Agent learning is a controlled evaluation loop—not uncontrolled self-modification.
Agent run
Outcome + trace
Evaluate failure type
Improve system asset
Regression evaluation
AGENTS.mdRole instructionsTask templatesContext assemblyTool permissionsPackage schemasSelection policiesEvaluation casesStop conditionsEscalation rulesPlaybooks
Only authorized files and boundaries changed.
No invented requirements or behavior.
Game policy stays out of the platform.
Tests and measurements are reproducible.
Stops on contract and authority changes.
Applies current authoritative artifacts.
Links outputs to requirements and packages.
Uses improved behavior on the next run.
14 · Experience learning
A technically correct game can still feel wrong
Human experiential review is a first-class evidence stream for responsiveness, clarity, delight, fairness, accessibility, and creative quality.
Sock Rescue review
Movement feels immediateLifecycle is understandablePause feels stableScoring feels satisfyingStreak is legibleGolden sock is excitingDog behavior is readableDifficulty feels fairFeedback is synchronizedHDMI output is readable
Structured capture
- Build and hardware version
- Participant profile
- Scenario and task
- Observed behavior
- Direct feedback
- Facilitator interpretation
- Severity or opportunity
- Recording or evidence
- Proposed design change
- Confidence and follow-up
15 · Systems analysis
Find mechanisms, not convenient blame
“The agent failed” or “the engineer missed it” is not a sufficient causal explanation.
Was the desired outcome clear?
Were requirements and assumptions explicit?
Could the executor make the necessary decision?
Was the package independently completable?
Were the right skills and tools available?
Did hardware or dependencies differ?
Could the test detect the problem?
Did component interactions create failure?
Did criteria reflect human perception?
Did a gate miss the issue or delay flow?
Did abstraction help, constrain, or mislead?
Did prior learning reach this executor?
Goal: identify the smallest systemic improvement that prevents recurrence or amplifies success.
16 · Horizons
Match learning cadence to scope
Active execution can be corrected immediately; broader generalization requires stronger evidence.
Correct an active agent or package during execution.
Improve the current feature at integration.
Learn from complete product behavior.
Improve a reusable service after consumer evidence.
Adjust investment and priority periodically.
Improve roles, policies, and system design.
17 · False learning
Resist conclusions that outrun the evidence
Every record states confidence, scope, excluded interpretations, and revalidation conditions.
Generalizing one unusual event
Treating correlation as causation
Rewriting standards after every defect
Capturing opinions without context
Letting the loudest reviewer define truth
Confusing workaround with reusable solution
Promoting game policy into platform code
Optimizing agent speed over correctness
Ignoring failed or negative runs
Retaining lessons after architecture changes
Measuring activity instead of outcomes
Completing retrospectives without behavior change
18 · Institutionalization
Change the authoritative asset—not only the learning record
The mechanism depends on what future behavior must become different.
Behavior or constraint changed.
Architectural understanding changed.
A defect must not recur.
An agent failure must be detected.
An execution technique improved.
Decomposition or evidence changed.
A reusable implementation proved value.
Authority or approval was inadequate.
Correct usage needs a concrete example.
Adoption friction exposed a gap.
Outcome assumptions changed.
Contributor understanding must improve.
19 · Effectiveness
Verify that institutionalization worked
An adopted lesson with no measurable behavioral change should be reconsidered.
Regression catches the original defect
Next agent follows the improved boundary
Board latency meets revised requirement
Reviewers perceive pause as immediate
Second consumer integrates faster
Package schema reduces blocked work
Revised gate catches compatibility risk
Exception recurrence decreases
20 · RP2350 example
Learn from Start, Pause, and Resume on target hardware
Automated tests and 100 hardware cycles pass, yet players report that Pause sometimes feels delayed.
Preserve exact environment
Compare timestamps
Separate actual vs perceived latency
Reproduce in harness
Route approved changes
Verify next build
| Evidence / finding | Destination | Institutional change |
|---|---|---|
| Input and lifecycle transition meet one frame | Execution evidence | Preserve deterministic state test |
| Audio response measures 27 ms | Knowledge + Platform | Add cross-modal quality contract |
| Four of five players perceive delay | Product + QA | Add structured experience criterion |
| Reference harness reproduces issue | Platform | Generalize beyond Sock Rescue |
| Revised build reaches ≤20 ms | Verification | Close effectiveness review |
| Second consumer passes same suite | Platform Promotion | Support lifecycle capability broadly |
Lifecycle correctness requires both deterministic state preservation and perceptually synchronized feedback.
21 · Health measures
Measure adoption, effectiveness, recurrence, and leverage
The engine succeeds when verified improvements propagate into future work—not when the retrospective count rises.
Meaningful changes reviewed for learning.
Findings embedded in authoritative artifacts.
Adopted improvements achieving success measures.
Known failures repeated after adoption.
Observation to adoption to verification.
Findings supported at the required level.
Signals reach the correct owning system.
Successful techniques become playbooks.
Evaluation performance after change.
Experience findings resolved in later builds.
Learning produces reusable capabilities.
Adopted but unverified improvements.
Learning Effectivenessverified improvements / adopted proposals
Recurrence Raterepeated known failures / relevant future changes
22 · System relationships
Learning recommends and routes; owning systems adopt
The engine synthesizes evidence without bypassing authority or becoming a shadow source of truth.
| System | Learning relationship |
|---|---|
| Strategy | Tests outcome assumptions and proposes amendments. |
| Knowledge | Corrects requirements, decisions, and constraints. |
| Execution | Improves packages, validation, orchestration, and playbooks. |
| Platform | Identifies reusable capabilities and evaluates consumer evidence. |
| Governance | Routes adoption decisions and improves policies. |
| Learning Engine | Synthesizes evidence, proposes improvements, verifies adoption. |
| Orchestrator | Detects triggers and routes approved changes. |
| Repository | Preserves organizational memory and authoritative improvements. |
23 · Operating contract
Evidence becomes improvement through a governed loop
The loop repeats until the proposed improvement is either disproved or verified in future behavior.
24 · Repository
Give evidence, findings, adoption, and verification a durable home
Organizational memory stays versioned beside the authoritative assets it improves.
Learning is a closed-loop operating contract
Signals are qualified, investigated, adopted through governance, routed into owning systems, and verified against future results.
Next design step: define the Learning Record Schema and Learning Adoption Policy.
learning/
├── charter/
│ └── learning-engine-charter.md
├── signals/
│ ├── execution/
│ ├── experience/
│ ├── platform/
│ ├── governance/
│ └── operations/
├── observations/
│ ├── active/
│ └── qualified/
├── investigations/
│ ├── active/
│ └── completed/
├── findings/
│ ├── proposed/
│ ├── adopted/
│ ├── rejected/
│ ├── deferred/
│ └── superseded/
├── evidence/
│ ├── measurements/
│ ├── human-feedback/
│ ├── agent-evaluations/
│ └── comparative-studies/
├── improvements/
│ ├── strategy/
│ ├── knowledge/
│ ├── execution/
│ ├── platform/
│ └── governance/
├── verification/
│ ├── pending/
│ └── completed/
├── evaluations/
├── metrics/learning-health/
└── templates/
playbooks/
├── capture-learning-signal/
├── investigate-finding/
├── conduct-experience-review/
├── propose-system-improvement/
├── evaluate-agent-run/
└── verify-learning-adoption/