From 314713e7db8bc15e79728d653a06623eb3137cee Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 5 Oct 2026 11:34:30 +0000 Subject: [PATCH] Record session-environment lessons and separate review axes. Fit navigation, tool economy, and no-op steering lessons into the existing correction ladder, and ask review to keep plan or spec misses separate from repository standards or simplicity. Co-authored-by: Dennis Geldmacher --- CHANGELOG.md | 2 ++ docs/behavior-validation.md | 3 +++ docs/manual-workflow.md | 4 ++-- docs/methodology-sources.md | 6 ++++++ docs/project-improvement.md | 2 +- references/learning-work.md | 12 ++++++------ skills/review-work/SKILL.md | 2 ++ 7 files changed, 22 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fb89740..9163bb7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Unreleased +- Learn from the session or its log about navigation, wasteful tool use, and steering instructions that do not change behavior. Mechanical lessons become checks; judgment lessons become standards the reviewer applies, so implementation context stays lean. Review keeps plan or spec deviation separate from repository standards or simplicity. + ## 7.7.0 - When a planning assignment is vague or underspecified, allow an optional short decision round with a recommendation. Clear assignments still need no interview. Raise the plan-and-readiness context limit to hold that instruction. diff --git a/docs/behavior-validation.md b/docs/behavior-validation.md index 165154c..a342e1f 100644 --- a/docs/behavior-validation.md +++ b/docs/behavior-validation.md @@ -95,6 +95,7 @@ For each example ask: What is the result? What does it mean for the goal? What f | Native implementation has only the approved plan and assignment. | The plan carries reporting expectations and the host's review invocation. The executor reports actual checks and recommends a separately commissioned Review, without claiming it passed. | [Planning](../skills/plan-work/SKILL.md), [implementation handoff](manual-workflow.md#plan-and-implementation), built host instructions | | Planning is asked to address a repeated correction, and both a structural change and a CI check could work. | Apply the learning guidance to choose the smallest sufficiently effective measure proportionate to the assignment. Prefer structural prevention among comparably proportionate options. Ask before a consequential design change; technical feasibility alone does not justify widening the plan. | [Planning](../skills/plan-work/SKILL.md), [learning guidance](../references/learning-work.md) | | A required check failed, although other checks passed. | State the failed behavior, consequence, and named correction. Recommend the host's correction invocation without starting it or claiming completion. | [Review](../skills/review-work/SKILL.md), CSV export example | +| The change matches the plan but breaks a repository convention, or it follows local conventions while missing specified behavior. | Report the axes separately: deviation from the plan or spec, and violation of repository standards or simplicity. A pass on one axis leaves the other intact. When simplicity is in question and the Efficiency plugin is already available, apply its design and code simplicity guidance in this same review. | [Review](../skills/review-work/SKILL.md) | | A required result is missing but an authorized local test route exists. | Explain the gap and a verification-only correction the human can commission; do not demand a human attestation or invent a code fix. | [Review](../skills/review-work/SKILL.md), settings example | | Actual earlier output covers the requirement and the relevant source, dependencies, configuration, and environment are unchanged. | Inspect provenance, output, coverage, and current applicability; explain the reuse basis without automatically rerunning the check. Still assess every success criterion. | [Review](../skills/review-work/SKILL.md), settings example | | Earlier passing output is followed by a relevant source, dependency, configuration, or environment change. | Recheck affected proof or report the current evidence gap; widen checks when the change or uncertainty warrants it. A success summary alone never proves applicability. | [Review](../skills/review-work/SKILL.md), [correction](../skills/correct-work/SKILL.md) | @@ -135,6 +136,8 @@ Use these scenarios for an instruction-level walkthrough of the [working agreeme | Existing guidance already addresses a recurring mistake, and an affordable CI check can detect it. | Recommend the check instead of adding the same guidance again. Keep implementation pending if the check falls outside the commissioned scope. | | The selected preventive repair is outside the current assignment. | Preserve it as a concrete future assignment with evidence, benefit, destination, expected outcome, and checks. Learning does not implement product, tool, or verifier repairs. | | Technical prevention is disproportionate, but Review confirms a useful bounded project instruction and learning is commissioned. | Save the supported guidance under the learning rules. A merely feasible technical alternative does not block an appropriate guidance update. | +| The session or its log shows a long search for an existing file, repeated expensive tool calls, or a steering instruction that changed nothing. | Record an environment lesson. Prefer a navigation pointer, a cheaper tool path, or removal of the dead instruction, using the existing prevention order. A one-off observation stays a candidate, not a permanent rule. | +| A repeated mistake is a fixed pattern a check can catch. Another is a judgment about consistency that no check can replace. | Turn the mechanical lesson into a check. Turn the judgment lesson into a standard the reviewer applies, and leave that standard out of implementation context. A dedicated standards file stays optional. | ## Engineering playbook decisions diff --git a/docs/manual-workflow.md b/docs/manual-workflow.md index 84414d6..18d953d 100644 --- a/docs/manual-workflow.md +++ b/docs/manual-workflow.md @@ -60,7 +60,7 @@ A successful implementation report is the input to review. It does not mean revi Review checks the result without changing repository files. It can use still-applicable evidence after checking its origin, output, and relevance; changed or uncertain evidence needs a fresh check. It must cover the whole plan, not just the tests that happened to pass. Test output may only be created outside the repository, and checks that cannot run within those limits remain visible gaps. -The result tells you whether the goal is achieved, corrections are needed, or proof is missing. A finding explains the observed problem, why it matters, what should change, and how to check the fix. +The result tells you whether the goal is achieved, corrections are needed, or proof is missing. A finding explains the observed problem, why it matters, what should change, and how to check the fix. Keep a miss against the plan or spec separate from a break with repository standards or simplicity, so one does not hide the other. ### 4. Correct findings, then review again @@ -87,7 +87,7 @@ For an Auto-Work handoff, also preserve the mode, correction budget already used ## Learning across reviews -Review can offer to save useful project knowledge, such as the verified download helper for CSV exports. Saving remains your choice. If the same correction has already come back, a structural change or a CI check is preferred over another guidance paragraph when it is sufficiently effective and proportionate to the assignment. See [how learning works](project-improvement.md#save-project-knowledge). +Review can offer to save useful project knowledge, such as the verified download helper for CSV exports. Saving remains your choice. If the same correction has already come back, a structural change or a CI check is preferred over another guidance paragraph when it is sufficiently effective and proportionate to the assignment. A session can also show a navigation failure, wasteful tool use, or a steering instruction that does not change behavior. See [how learning works](project-improvement.md#save-project-knowledge). ## Supporting work diff --git a/docs/methodology-sources.md b/docs/methodology-sources.md index d2beee5..f8a6378 100644 --- a/docs/methodology-sources.md +++ b/docs/methodology-sources.md @@ -43,6 +43,12 @@ An optional short decision round for a vague or underspecified assignment is the Workflow does not add a grill-me or grill-with-docs skill, a required glossary, a product-design interview, or a mandatory interview before planning or Auto-Work. Product-design judgment stays with the Design plugin when that plugin is in use. Material security or auth effects stay on plan-work's existing second-order line. Change sketches stay with Efficiency's change-communication. Packaged instructions remain original Workflow wording. This note attributes the idea; it does not load an upstream skill. +## Agent environment and two-axis review + +Session-environment lessons and the split between plan or spec deviation and repository standards or simplicity are adapted from Matt Pocock's [retro](https://github.com/mattpocock/skills/blob/24fe0ef7737efae15c87225755e9f6f5965e4888/skills/engineering/retro/SKILL.md) and [code-review](https://github.com/mattpocock/skills/blob/24fe0ef7737efae15c87225755e9f6f5965e4888/skills/engineering/code-review/SKILL.md) skills in `mattpocock/skills` v1.3.1, commit `24fe0ef7737efae15c87225755e9f6f5965e4888`, announced at . Workflow keeps the existing correction ladder in the [learning guidance](../references/learning-work.md). It adds the session or log as a source for environment lessons: navigation, tool economy, and steering instructions that do not change behavior. Mechanical lessons become checks. Judgment lessons become standards the reviewer applies, so implementation context stays lean. Review reports both axes in the same read-only pass. When simplicity is in question and the Efficiency plugin is already available, that pass may use its design and code simplicity guidance, inspected in `geldmacher/efficiency` at `e8d81d02af5071484383896e1ab1cf4a585f267d`. + +Automated checks were already on the ladder. This adaptation does not add a `/retro` command, a required `CODING_STANDARDS.md`, parallel review subagents, or the Fowler smell baseline. It does not adopt `/implement-spec`, which conflicts with Auto-Work, the written plan handoff, and host-configured models. Grill-me, grill-with-docs, and a required glossary stay out, as [Vague-scope planning](#vague-scope-planning) already records. Packaged instructions remain original Workflow wording. This note attributes the ideas; it does not load the upstream skills. + ## Shared integration decisions Each method remains one reference file. Catalog and skill entrypoints load only the selected method. The playbooks describe useful result content, not mandatory user-document headings, metadata, or machine state. diff --git a/docs/project-improvement.md b/docs/project-improvement.md index 626614e..3db84d3 100644 --- a/docs/project-improvement.md +++ b/docs/project-improvement.md @@ -70,7 +70,7 @@ A subagent role is optional, narrowly scoped and tested through actual discovery During implementation and correction, Workflow records useful discoveries as **learning candidates**: proposed lessons with evidence, a future benefit, where they apply, and where they could be saved. Collection happens as part of the work; it does not silently change project instructions. -When a correction recurs despite a fix or existing guidance, follow the [learning guidance](../references/learning-work.md) to choose prevention proportionate to the task. A structural change or CI check can be more useful than another guidance paragraph, but technical feasibility alone does not justify a large change. A first finding can also justify proportionate prevention within its assignment. Learning saves supported, bounded guidance only when requested and appropriate; larger repairs remain future assignments. +When a correction recurs despite a fix or existing guidance, follow the [learning guidance](../references/learning-work.md) to choose prevention proportionate to the task. A structural change or CI check can be more useful than another guidance paragraph, but technical feasibility alone does not justify a large change. A first finding can also justify proportionate prevention within its assignment. The session or its log can also show where the agent could not find something, wasted tool calls, or followed an instruction that changed nothing. Mechanical lessons become checks. Judgment lessons become standards the reviewer applies. Learning saves supported, bounded guidance only when requested and appropriate; larger repairs remain future assignments. Every review checks earlier and new candidates against the current work. If any lessons are confirmed and useful, it offers `learn-from-work`. A lesson can be sound even when an unrelated code correction remains; the learning offer does not change the review judgment. If there is nothing useful to save, there is no offer. diff --git a/references/learning-work.md b/references/learning-work.md index e1c0eba..11a5911 100644 --- a/references/learning-work.md +++ b/references/learning-work.md @@ -4,16 +4,16 @@ Keep learning in the native task's existing reports and handoffs. Reading this g Capture reusable insights from the work, including successful corrections and diagnosis. For each candidate, explain the lesson, future benefit, supporting observations, scope and conditions, and proposed change with its destination. Use recognizable names, not formal IDs. Keep unconfirmed candidates distinct from review-confirmed lessons; a one-off observation is not a permanent rule. -For recurring findings, choose the smallest sufficiently effective prevention proportionate to effort and commissioned scope. With comparable effort and scope, prefer eliminating the class structurally, then CI checks, bounded guidance, and human review. A first finding may justify in-scope prevention without automatically widening the assignment. +For recurring findings, choose the smallest sufficiently effective prevention proportionate to effort and commissioned scope. With comparable effort and scope, prefer eliminating the class structurally, then CI checks, bounded guidance, and human review. A first finding may justify in-scope prevention without automatically widening the assignment. Read the session or log as an environment source: navigation, wasteful tool use, and no-op steering instructions. Mechanical lessons become checks. Save a judgment lesson as a reviewer standard outside implementation context when Review confirms it is reusable and learning is commissioned; until then it stays a review finding or an open candidate. -Keep one complete, compact collection of open candidates in the native task, including evidence references. Subsequent phase reports and handoffs carry what changed and an accessible reference to that collection. Include the full collection when the receiver cannot access the reference. Retain concise outcomes and reasons for integrated, merged, rejected, or superseded candidates, with their destinations or successors where relevant. Keep those records and their basis accessible throughout the workflow. Missing history or evidence stays an explicit gap, never a claim of a complete collection. Preserve unaffected work while resolving the gap before dependent learning. +Keep one complete, compact collection of open candidates in the native task, with evidence references. Later reports and handoffs carry what changed and an accessible reference, or the full collection when that reference is unreachable. Retain concise outcomes and reasons for integrated, merged, rejected, or superseded candidates, with destinations or successors, and keep that basis accessible throughout the workflow. Missing history or evidence stays an explicit gap, never a claim of a complete collection. Preserve unaffected work while resolving the gap before dependent learning. -Reconcile candidates whenever relevant work changes, and reassess both inherited and new candidates at every Review. Check the current repository, guidance, and later observations. Merge duplicates; distinguish conditions and scopes before treating lessons as contradictory. Refine, replace, or reject a candidate only with supporting evidence and a reason; newer does not automatically mean correct. Keep unresolved conflicts open and withhold the affected changes. Independent confirmed candidates may proceed. Recheck integrated lessons when later work affects their basis; propose a bounded update or removal for the next learning assignment rather than silently changing guidance during another phase. +Reconcile candidates whenever relevant work changes, and reassess both inherited and new candidates at every Review. Check the current repository, guidance, and later observations. Merge duplicates; distinguish conditions and scopes before treating lessons as contradictory. Refine, replace, or reject a candidate only with evidence and a reason; newer does not automatically mean correct. Keep unresolved conflicts open and withhold the affected changes. Independent confirmed candidates may proceed. Recheck integrated lessons when later work affects their basis; propose a bounded update or removal for the next learning assignment rather than silently changing guidance during another phase. -At a Review, offer newly confirmed or materially changed applicable lessons, with their benefits and the matching action. On a final positive Review, surface an unchanged eligible offer once when it has been neither accepted nor rejected. Do not restate an unchanged offer on an intermediate correction Review. A completed Review may establish a lesson even when the overall goal still needs corrections; the lesson's own basis must be supported. Keep necessary corrections and missing acceptance proof prominent. Offers neither change the Review judgment nor add a required step to an achieved goal. With no eligible lessons, omit the offer. Unaccepted candidates remain open for later rounds; an explicit rejection is recorded with its reason. +At a Review, offer newly confirmed or materially changed applicable lessons, with their benefits and the matching action. On a final positive Review, surface an unchanged eligible offer once if it was neither accepted nor rejected; do not restate it on an intermediate correction Review. A completed Review may establish a lesson even when the goal still needs corrections; its basis must be supported. Keep necessary corrections and missing acceptance proof prominent. Offers neither change the Review judgment nor add a required step to an achieved goal. With no eligible lessons, omit the offer. Unaccepted candidates stay open; record an explicit rejection with its reason. On a commissioned learn-from-work invocation, consider all open candidates unless the human selects a narrower scope. Reconcile the collection again before edits, including interactions among the proposed changes and with existing guidance. Require completed Review evidence for each lesson and verify it still applies. Ask about unresolved consequential content, authority, or destination choices before the affected edits; continue independent authorized learning. Do not turn unsupported observations into rules or silently discard blocked candidates. -Use existing project guidance or appropriate skills and learning conventions. Save only bounded, reusable, demonstrated guidance; preserve unrelated instructions. Guidance updates must not implement product, tool, or verifier repairs. Route those and Workflow plugin changes beyond bounded guidance updates into concrete future development assignments with evidence, benefit, destination, expected outcome, and checks. Keep these pending until separately handled or explicitly rejected; learn-from-work does not authorize their implementation. Personal memory requires an explicit request for that memory. +Use existing project guidance or appropriate skills and learning conventions. Save only bounded, reusable, demonstrated guidance; preserve unrelated instructions. Guidance updates must not implement product, tool, or verifier repairs. Route those and Workflow plugin changes beyond bounded guidance updates into concrete future development assignments with evidence, benefit, destination, expected outcome, and checks. Keep these pending until separately handled or explicitly rejected; learn-from-work does not authorize their implementation. Personal memory requires an explicit request. -After edits, read back the affected guidance and check that the combined result is consistent and preserves unrelated content. Only verified saved changes count as integrated. Report destinations, evidence, integrated or merged lessons, rejected or superseded lessons and reasons, and the complete remaining open collection. Partial write failures leave unfinished work open; report partial results accurately and repair only own bounded changes when authorized. On repeated invocations, compare actual saved guidance before adding anything, including after an interrupted prior invocation; do not duplicate rules or claim an unsaved change succeeded. +After edits, read back the affected guidance and check that the combined result is consistent and preserves unrelated content. Only verified saved changes count as integrated. Report destinations, evidence, integrated or merged lessons, rejected or superseded lessons and reasons, and the complete remaining open collection. Partial write failures leave unfinished work open; report partial results accurately and repair only own bounded changes when authorized. On a repeated or interrupted invocation, compare actual saved guidance before adding anything; do not duplicate rules or claim an unsaved change succeeded. diff --git a/skills/review-work/SKILL.md b/skills/review-work/SKILL.md index e4a4c56..6aacd57 100644 --- a/skills/review-work/SKILL.md +++ b/skills/review-work/SKILL.md @@ -15,6 +15,8 @@ Match optional methods and verifier edits to active selections. For setup change Lead with a reasoned judgment: goal achieved, corrections needed, or open points. Failed necessary checks prevent goal achieved. Missing necessary proof, unclear scope, or missing plan versions remain explicit, even when there are also correctable defects. +Keep both axes visible: plan or spec deviation, and repository standards or simplicity. On a simplicity question, use available Efficiency guidance. + Assess inherited and new learning candidates from the reviewed work. When any exist, follow the learning guidance linked by the working agreement: reconcile the whole collection and offer newly confirmed or materially changed lessons. On a final positive Review, surface an unchanged eligible offer once if it was neither accepted nor rejected; do not restate it on an intermediate correction Review. Keep Review read-only. For each actionable defect, explain observed behavior, evidence, impact on the plan, required correction, permitted scope, and recheck. This can serve as the correction assignment. In standalone work, recommend that the human commission the corrections. In Auto-Work, return findings to the commissioned loop. For missing proof, name the check and a permitted way to obtain it; verification-only correction needs no code change. Consequential decisions or missing access remain explicit. Do not ask the human to attest evidence the executor can collect under its assignment. A positive Review establishes repository acceptance criteria, not Auto-Work's remaining human acceptance or delivery. Finish without starting correction or delivery.