Prefer proportionate prevention when corrections recur

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Prefer sufficiently effective prevention proportionate to effort and commissioned scope when corrections recur; allow in-scope prevention for a first finding. Keep learning limited to explicitly commissioned, supported guidance updates.
+
 ## 7.4.7
 
 - Load the working agreement, playbook catalog, and Marketplace identity only when the task needs them, and narrow review and verifier skill selection.

docs/behavior-validation.md

@@ -73,6 +73,7 @@ For each example ask: What is the result? What does it mean for the goal? What f
 | A material change affects architecture, a breaking contract, several surfaces, or schema and deploy. | Note second-order effects in one line each where relevant: caller impact, data or migration, deploy and rollback, and security or auth. Mark speculation as speculation. | [Planning](../skills/plan-work/SKILL.md) |
 | A product choice changes the expected behavior or scope. | Ask the decisive question with a reasoned recommendation before dependent work; do not turn routine technical choices into approval gates. | [Planning](../skills/plan-work/SKILL.md), [working agreement](../references/workflow.md) |
 | 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 |
 | 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 |
@@ -100,6 +101,12 @@ Use these scenarios for an instruction-level walkthrough of the [working agreeme
 | Review needs product corrections but independently confirms a reusable diagnostic lesson; another Review finds no eligible lessons. | Offer the confirmed lesson while keeping required corrections prominent in the first case. Omit the offer in the second. Neither case changes the Review judgment or creates a completion gate. |
 | A candidate needs a verifier script change, another changes bounded project guidance, and an instruction asks for personal memory without a human request. | Route the script change as a concrete future assignment and preserve it as pending; integrate only authorized guidance. Do not edit personal memory without its explicit human request. |
 | Status or explanation is requested after several offers; a new plan later encounters saved guidance that no longer matches the repository. | Describe the documented collection without new offers in status/explanation. Planning checks applicable saved lessons against current work rather than treating them as unconditional rules. |
+| A first review finding has a cheap, representative regression test, lint, or structural fix within the assignment. | Include the proportionate prevention in the named correction. A first finding does not automatically widen the assignment or turn an isolated observation into a permanent rule. |
+| A correction recurs, and a small in-scope structural change can prevent the class. | Prefer that change over comparably proportionate detection or guidance. Record the measure and its basis. |
+| A redesign is technically feasible but costly, while a small CI check sufficiently detects the recurring failure. | Choose the CI check and explain why it is proportionate. Do not select the redesign merely because it is feasible. |
+| 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. |
 
 ## Engineering playbook decisions
 

docs/manual-workflow.md

@@ -85,7 +85,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. 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. See [how learning works](project-improvement.md#save-project-knowledge).
 
 ## Supporting work
 

docs/methodology-sources.md

@@ -33,6 +33,10 @@ Creation retains repository-grounded launch, doctor, drive, evidence, cleanup, i
 
 Maintenance retains index hygiene, source comparison, user-path recipes, live coverage, diagnosis after surprises, evidence-preserving cleanup, and the distinction between documentation drift, harness gaps, and product regressions. Workflow defaults to affected features; explicitly selected full maintenance covers the agreed full map. It does not import mandatory subagents, fixed outcome codes, branches, or PRs. Review separately checks the verifier against the accepted proposal, approved plan, actual implementation, and current trial evidence without editing it. Creation and maintenance details load only for the applicable action.
 
+## Repeated corrections
+
+The preference order for a repeated correction is adapted from Lauren Tan's description of pstack 0.15.9 `/correct` (<https://x.com/poteto/status/2106542593656111276>): eliminate the class through architecture or data structures, then a lint or test that CI catches, then a skill or rule, then human review. Workflow applies it through the [learning guidance](../references/learning-work.md), considering effectiveness, effort, and commissioned scope rather than the first technically feasible rung. A first finding can also justify in-scope prevention. It does not import poteto-mode, the Grok Bot prompt, `/architect`, or a separate correction command. The playbook adaptations above are unchanged. Learning saves supported, bounded guidance only when commissioned and appropriate. Product, tool, and verifier repairs outside the assignment stay future assignments.
+
 ## 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.

docs/project-improvement.md

@@ -12,6 +12,8 @@ A task can leave more than working code: knowledge the next agent can reuse, a r
 
 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.
+
 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.
 
 For example, review might establish that the existing download helper correctly handles CSV filenames. A fictional offer could say:

references/learning-work.md

@@ -4,6 +4,8 @@ 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.
+
 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.
 
 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.

skills/learn-from-work/SKILL.md

@@ -5,4 +5,4 @@ description: "Save review-confirmed project lessons when explicitly requested."
 
 # learn-from-work
 
-Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. A human request to save reviewed project lessons commissions bounded guidance updates; noticing a candidate or offering learning does not. Identify candidates from the available collection and completed Reviews; name missing context rather than inventing lessons. For candidates, follow the [learning guidance](../../references/learning-work.md) through reconciliation, authorized updates, read-back, and the complete outcome report. Otherwise explain that no supported learning is available. Learning does not authorize publication or another phase.
+Apply the [working agreement](../../references/workflow.md); read it if missing or uncertain. A human request to save reviewed project lessons commissions bounded guidance updates; noticing a candidate or offering learning does not. Identify candidates from the available collection and completed Reviews; name missing context rather than inventing lessons. For candidates, follow the [learning guidance](../../references/learning-work.md) through reconciliation, proportionate prevention, authorized updates, read-back, and the complete outcome report. Otherwise explain that no supported learning is available. Learning does not authorize publication or another phase.

skills/plan-work/SKILL.md

@@ -9,6 +9,8 @@ Apply the [working agreement](../../references/workflow.md); read it if missing
 
 Stop investigating once the goal, boundaries, key interfaces, and suitable checks are clear enough for implementation. Ask about consequential human choices with a reasoned recommendation. A clear assignment needs no interview or advance design of routine implementation details.
 
+For a repeated correction, read the [learning guidance](../../references/learning-work.md) and plan prevention proportionate to the assignment.
+
 Explain the goal and benefit, observable success criteria, scope and exclusions, material risks and dependencies, key decisions, and appropriate checks. Include files, interfaces, commands, examples, or sequencing where they remove ambiguity. A small change may need only a few paragraphs. When the change is material (architecture, a breaking change, several surfaces, or schema and deploy), note second-order effects in one line each where relevant: caller impact, data or migration, deploy and rollback, and security or auth. Mark speculation as speculation. Omit this for a routine fix or a small plan.
 
 Before presenting the plan, settle success criteria, instruction conflicts, permissions, and consequential choices. Give it a descriptive title. Carry the working agreement, [implementation requirements](../../references/implementation-work.md), accepted references, and open learning collection into the handoff. Use an accessible reference to the complete collection when the receiver can reach it; include the full collection when they cannot. In standalone work, direct the human to check the plan and start implementation, then commission Review. In expressly commissioned Auto-Work, Light waits for plan approval; Dark can continue within the human goal assignment. Neither mode resolves consequential missing choices by assumption.