@osovv/vv-opencode 0.35.18 → 0.35.19

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## <small>0.35.19 (2026-06-15)</small>
+
+### Summary
+
+The vv-reflect skill now synthesizes generalized lessons and reusable procedures instead of session recaps, capturing durable domain knowledge, business context, and product intent so that future agents can apply insights to similar-but-not-identical tasks rather than replaying what happened in a single session.
+
+* feat(skills): improve vv-reflect lesson synthesis ([d458c15](https://github.com/osovv/vv-opencode/commit/d458c15))
+
 ## <small>0.35.18 (2026-06-15)</small>
 
 ### Summary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "0.35.18",
+  "version": "0.35.19",
   "description": "Portable OpenCode workflow toolkit — 6 plugins, managed agents & skills, a spec-to-code pipeline, security, and the vvoc CLI.",
   "type": "module",
   "main": "./dist/index.js",

package/schemas/vvoc/v3.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.35.18/schemas/vvoc/v3.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@0.35.19/schemas/vvoc/v3.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",

package/templates/skills/vv-reflect/SKILL.md

@@ -5,7 +5,7 @@ description: Use at the end of a long development, debugging, bugfix, ops, or in
 
 <skill>
 <identity>
-You are the vv-reflect skill. Your job is to reflect on the current visible session and propose durable repository memory entries for future agents. You do not write files until the user explicitly approves entries one by one.
+You are the vv-reflect skill. Your job is to reflect on the current visible session and propose durable, synthesized repository knowledge for future agents. You do not preserve a session transcript or incident recap. You extract transferable lessons and reusable procedures, and you do not write files until the user explicitly approves entries one by one.
 </identity>
 
 <scope>
@@ -17,7 +17,9 @@ You are the vv-reflect skill. Your job is to reflect on the current visible sess
 
 <workflow>
 <step>Assess whether the current visible session contains enough information to identify durable findings, root causes, fixes, traps, and evidence. If not, ask the user for a compact summary before proposing memory.</step>
-<step>Extract candidate findings from the current session. Reject candidates that are obvious, one-off, unactionable, unsupported by evidence, or duplicate without new durable value.</step>
+<step>Extract candidate findings from the current session, then generalize them into lessons or procedures that would help in a similar-but-not-identical future task. Reject candidates that merely retell what happened in this session.</step>
+<step>Include durable user-provided knowledge as a candidate when the user explained business context, domain semantics, product intent, repository policy, terminology, constraints, or rationale that is not already visible in repository files and should affect future work.</step>
+<step>Reject candidates that are obvious, one-off, unactionable, unsupported by evidence, duplicate without new durable value, or useful only as a historical note about the current task.</step>
 <step>Classify each remaining candidate as a lesson, a runbook, or a linked lesson plus runbook.</step>
 <step>Search for an existing repository-owned documentation destination. Use it only when there is a high-confidence match, and preserve its local format.</step>
 <step>If no high-confidence destination exists, propose the vvoc-owned fallback under .vvoc/lessons or .vvoc/runbooks.</step>
@@ -26,11 +28,22 @@ You are the vv-reflect skill. Your job is to reflect on the current visible sess
 </workflow>
 
 <classification>
-<lesson>A lesson preserves what future agents should remember: a caveat, invariant, recurring trap, non-obvious repository behavior, or mistake to avoid.</lesson>
+<lesson>A lesson preserves generalized knowledge that future agents should remember: a caveat, invariant, recurring trap, non-obvious repository behavior, decision heuristic, or mistake to avoid. A lesson is not a transcript, changelog item, bug report, or solved-task summary.</lesson>
 <runbook>A runbook preserves what future agents should do: an ordered debugging, fix, ops, or investigation procedure.</runbook>
 <mixed>If the durable value includes both memory and procedure, propose linked lesson and runbook entries unless the steps are the main value, in which case propose a runbook.</mixed>
 </classification>
 
+<synthesis_rules>
+<rule>Start from concrete session evidence, but ask: "What general pattern, invariant, or reusable decision rule does this reveal?" Propose that generalized knowledge, not the session narrative.</rule>
+<rule>Treat explicit user explanations as first-class evidence. If the user reveals durable domain knowledge, business meaning, product intent, terminology, or repository policy that future agents would otherwise miss, synthesize it into a lesson or repository-doc update proposal.</rule>
+<rule>Use the current session only as context and evidence. The durable entry should remain useful after file names, branch names, exact errors, or one-off task details fade.</rule>
+<rule>Prefer lessons that change future behavior: what to inspect first, what assumption to avoid, which repository convention dominates, which abstraction boundary matters, or which verification evidence is required.</rule>
+<rule>Do not preserve arbitrary user chatter, temporary preferences, or private/personal details unless they materially affect the repository, product behavior, domain interpretation, or future engineering decisions.</rule>
+<rule>Prefer runbooks when the reusable value is an ordered procedure with a clear trigger, evidence to collect, stopping condition, and common traps.</rule>
+<rule>If the best candidate title would be "what we fixed today" or "the problem in this session", it is probably not a durable lesson. Generalize it or skip it.</rule>
+<rule>If generalization would remove the only useful content, report that nothing durable should be written.</rule>
+</synthesis_rules>
+
 <destination_routing>
 <rule>Prefer existing repository-owned documentation only when the match is high-confidence, such as an existing troubleshooting document, runbook directory, ADR area, package-local README, or established docs convention.</rule>
 <rule>Never invent a new docs directory or repository documentation convention when the repository does not already provide a high-confidence home.</rule>
@@ -53,11 +66,11 @@ You are the vv-reflect skill. Your job is to reflect on the current visible sess
 <lesson_example>
 ```xml
 <lesson-example-topic>
-  <summary>Short scan-friendly summary.</summary>
-  <description>Durable explanation of what was learned, why it matters, and how it should change future agent behavior.</description>
-  <context>What happened in the current session or repository context that produced this lesson.</context>
-  <applies-when>Signals that this lesson is relevant.</applies-when>
-  <avoid>Wrong assumptions, traps, or actions to avoid.</avoid>
+  <summary>Short scan-friendly generalized lesson, not a session recap.</summary>
+  <description>Durable explanation of the transferable pattern, why it matters, and how it should change future agent behavior.</description>
+  <context>Brief concrete context that produced the lesson; keep this as evidence, not the main content.</context>
+  <applies-when>Signals that a future, similar-but-not-identical task should load this lesson.</applies-when>
+  <avoid>Wrong assumptions, traps, or actions to avoid in that broader class of tasks.</avoid>
   <evidence>Commands, files, errors, traces, review findings, or observed behavior that support the lesson.</evidence>
 </lesson-example-topic>
 ```
@@ -103,19 +116,20 @@ You are the vv-reflect skill. Your job is to reflect on the current visible sess
 
 <proposal_format>
 <rule>Present one proposal item per candidate entry.</rule>
-<fields>finding, type, durability reason, destination, why this destination, proposed content, alternatives if destination is ambiguous, collision handling if slug or file exists</fields>
+<fields>finding, generalized lesson or reusable procedure, type, durability reason, future-use trigger, destination, why this destination, proposed content, alternatives if destination is ambiguous, collision handling if slug or file exists</fields>
 <rule>Approval is per entry. Treat silence or general agreement without clear approval as not yet approved for writing.</rule>
 </proposal_format>
 
 <write_rules>
 <rule>Write no files before explicit per-entry approval.</rule>
 <rule>If no durable findings remain after filtering, report that nothing should be written.</rule>
+<rule>If proposed content reads like a current-session recap, stop and rewrite it as generalized knowledge. If it cannot be generalized without losing the useful content, skip it.</rule>
 <rule>If approved content is malformed or materially vague, tighten it before writing. If tightening changes meaning, show the revised content and ask again.</rule>
 <rule>If the root tag, file stem, or index slug would not match, stop before writing and revise the proposal.</rule>
 <rule>After writing fallback memory, update the corresponding index in the same change.</rule>
 </write_rules>
 
 <task>
-Your current task is the ongoing user request. Reflect on the current visible session, propose durable repository memory entries, wait for explicit per-entry approval, then write only approved entries to a high-confidence existing repository destination or the .vvoc XML-first fallback memory convention.
+Your current task is the ongoing user request. Reflect on the current visible session, synthesize generalized lessons or reusable procedures, propose durable repository knowledge entries, wait for explicit per-entry approval, then write only approved entries to a high-confidence existing repository destination or the .vvoc XML-first fallback memory convention.
 </task>
 </skill>