Assistant/architecture/adrs/ADR-0016-experience-reflection-skill-evolution.md

ADR-0016 — Experience, Reflection and Skill Evolution Foundation V1

Status: Accepted

Task: DEV-000067

Context

Domovoy can now receive human utterances, interpret intent, optionally plan work, resolve capabilities, perform narrow actions through existing owner boundaries, observe outcomes and accept human responses. The next architecture step is to preserve what happened and why, so repeated successful understanding may become reusable skill while failures, corrections and drift can return the system to broader thinking.

This must not introduce a giant learning manager, self-modifying loop, prompt optimizer or permanent hand-coded user profile. Learning evidence must remain historical and revisable.

Decision

1. Do not create a new canonical owner for DEV-000067.
2. epistemics owns provider-neutral experience, expectation, outcome and reflection-candidate semantics because these are evidence/provenance about what happened and why. It stores typed references to Interaction, Continuity, Work and Capability records rather than copying their canonical state.
3. capability owns skill-profile and fast-path lifecycle semantics because Skill V1 is a reusable capability/implementation pattern derived from evidence, not a new authority or profession category.
4. A SystemExpectation records what the system expected from meaningful help before outcome is known. "Model returned text" and "HTTP 200" are not sufficient success semantics.
5. ExperienceRecord links original human intent/utterance, context refs, selected help method, capability/implementation refs, expectation, outcome class, human response/correction refs and verification evidence.
6. ReflectionCandidate is append-only evidence that broader reflection may be warranted. It may be deterministic or routed through the Cognitive Gateway, but model output cannot directly mutate canonical beliefs, skills, authority, Go source or deployment.
7. Skill lifecycle is explicit: CANDIDATE, EVALUATING, VALIDATED, DEGRADED, SUSPENDED, RETIRED. Replacing or suspending a skill never deletes source observations, experiences, corrections, outcomes, beliefs or original human intent history.
8. Fast paths are optimizations, not truth. Every optimized path must be able to return NOT_APPLICABLE, LOW_CONFIDENCE, OUT_OF_DISTRIBUTION, CONFLICT or STALE and escalate to broader reasoning/clarification.
9. User corrections are strong learning evidence but are not automatically permanent rules. They create experience/reflection evidence and may later support revisable beliefs or skill changes.

Boundaries

• Interaction remains canonical owner of conversations, utterances, original human intent and corrections.
• Continuity remains canonical owner of HumanResponse, Attention and ProspectiveItem continuation state.
• Capability remains canonical owner of capability implementations, gaps, usage observations and skill profiles.
• Epistemics records evidence/reflection using typed refs only; it does not mutate other owners.
• No external mutation, new authority, new provider adapter, deployment authority expansion or self-modifying code path is introduced.
• Cognitive reflection, if later used, must go through Cognitive Gateway/Router and structured validation.

Non-goals

• No LearningManager, reinforcement-learning platform, autonomous curriculum, skill dashboard, universal user profile, plugin marketplace or self-modifying development loop.
• No automatic activation/promotion of cognitive models or capability implementations.
• No new canonical owner.

Consequences

• Production evidence such as reminder acceptance, human correction, capability gaps, cognitive advisory outcomes and repeated capability failures can be represented consistently.
• Validated fast paths can stay cheap, while stale/low-confidence/out-of-distribution cases can return to thinking instead of being forced into old rules.
• Knowledge and experience survive skill implementation replacement.