legrab · legrab · Aug 9, 2026 · Aug 9, 2026
@@ -27,19 +27,21 @@ sample/common/.agents/skills/structured-change/knowledge/engineering/documentati
 sample/common/.agents/skills/structured-change/knowledge/engineering/maintainability.md	1319
 sample/common/.agents/skills/structured-change/knowledge/engineering/modernization.md	1254
 sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md	1287
-sample/common/.agents/skills/structured-change/SKILL.md	1946
+sample/common/.agents/skills/structured-change/SKILL.md	2599
 sample/common/.agents/skills/structured-change/templates/design.md	649
 sample/common/.agents/skills/structured-change/templates/exploration.md	368
-sample/common/agentic-flow/.managed-files	170
+sample/common/.agents/skills/structured-change/templates/structure.md	175
+sample/common/agentic-flow/.managed-files	183
 sample/common/agentic-flow/.managed-skills	86
 sample/common/agentic-flow/.template-version	6
-sample/common/agentic-flow/AGENTS.md	5328
+sample/common/agentic-flow/AGENTS.md	5447
+sample/common/agentic-flow/ARTIFACTS.md	2333
 sample/common/agentic-flow/CONFIGURE.md	4475
 sample/common/agentic-flow/DECISIONS.md	963
 sample/common/agentic-flow/EDUCATION.md	5232
 sample/common/agentic-flow/LEARN.md	1822
-sample/common/agentic-flow/LOCAL.md	3513
-sample/common/agentic-flow/README.md	2907
+sample/common/agentic-flow/LOCAL.md	4179
+sample/common/agentic-flow/README.md	2979
 sample/common/agentic-flow/REFERENCE_INTEGRATION.md	2183
 sample/common/agentic-flow/ROOT_INTEGRATION.md	3086
 sample/common/agentic-flow/SETTINGS.md	544
@@ -76,20 +78,20 @@ sample/profiles/full/learning-flow/.managed-files	137
 sample/profiles/full/learning-flow/.managed-skills	132
 sample/profiles/full/learning-flow/.template-profile	5
 sample/profiles/full/learning-flow/.template-version	6
-sample/profiles/full/learning-flow/AGENTS.md	4458
+sample/profiles/full/learning-flow/AGENTS.md	4716
 sample/profiles/full/learning-flow/BOOTSTRAP.md	1788
 sample/profiles/full/learning-flow/MAP.md	1464
 sample/profiles/full/learning-flow/PLAYBOOKS.md	1327
 sample/profiles/full/learning-flow/README.md	2955
 sample/profiles/full/learning-flow/REPOSITORIES.md	439
 sample/profiles/full/learning-flow/TAKEAWAYS.md	970
 sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md	2010
-sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md	3574
+sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md	3718
 sample/profiles/minimal/learning-flow/.managed-files	87
 sample/profiles/minimal/learning-flow/.managed-skills	20
 sample/profiles/minimal/learning-flow/.template-profile	8
 sample/profiles/minimal/learning-flow/.template-version	6
-sample/profiles/minimal/learning-flow/AGENTS.md	2369
+sample/profiles/minimal/learning-flow/AGENTS.md	2633
 sample/profiles/minimal/learning-flow/MAP.md	1229
 sample/profiles/minimal/learning-flow/README.md	1974
 sample/profiles/minimal/learning-flow/TAKEAWAYS.md	973
@@ -100,15 +102,15 @@ scripts/install.bat	1477
 scripts/install.ps1	40236
 scripts/install.sh	34910
 scripts/README.md	6771
-skill-evals/agentic-cases.yaml	8332
+skill-evals/agentic-cases.yaml	8895
 skill-evals/conversation-cases.yaml	3653
-skill-evals/full-cases.yaml	4248
-skill-evals/minimal-cases.yaml	3208
+skill-evals/full-cases.yaml	4640
+skill-evals/minimal-cases.yaml	3655
 skill-evals/README.md	1667
-skill-evals/structured-change-cases.yaml	3735
+skill-evals/structured-change-cases.yaml	4710
 adoption/ADOPT.md	3941
 adoption/README.md	2057
-sample/common/.agents/skills/learning-closure/SKILL.md	3263
+sample/common/.agents/skills/learning-closure/SKILL.md	3911
 sample/common/.agents/skills/learning-freshness/SKILL.md	1866
-skill-evals/learning-lifecycle-cases.yaml	1220
+skill-evals/learning-lifecycle-cases.yaml	1599
 skill-evals/adoption-cases.yaml	1337
@@ -28,6 +28,15 @@ flowchart LR
 - **Unknown:** whether the ERP client is idempotent, i.e. whether a retried submission can duplicate an order.
 - **Control boundary:** production deployment and approval stay human-controlled.
 
+## How the model was built (two rounds, not one investigation)
+
+Round 1 — question: where does an approval request enter the system?
+Evidence: the approval endpoint and `OrderService`. Understanding after round 1: operator → endpoint → OrderService → (unknown past this point).
+
+Round 2 — question: what happens after `OrderService`? Evidence:
+`ApprovalRules`, the approval stored procedure, the ERP client.
+Understanding after round 2 is the full flow shown above — sufficient to evaluate the retry proposal, so investigation stops here.
+
 ## Why this is not just implemented as proposed
 
 The proposal ("wrap the call with retries") is treated as a hypothesis, not

@@ -36,6 +36,12 @@ Choose among:
 
 Prefer the module's own documentation when the knowledge is necessary to use or extend that module correctly. Prefer learning-flow surfaces for cross-cutting repository understanding.
 
+## Prefer changed understanding over new facts
+
+Before stating the candidate insight, check whether the most valuable thing learned is not a new fact but a correction to how investigation should happen next time — for example "trace the queue consumer before reasoning about downstream behavior" is more durable than "ERP submission is asynchronous." Prefer capturing the corrected reasoning pattern when one exists.
+
+If this session corrected an existing `learning-flow/MAP.md` or `TAKEAWAYS.md` entry, flag that entry as needing an update in the same closure pass — do not leave a known-stale record for `learning-freshness` to catch later.
+
 ## Ask at meaningful closure
 
 At pull-request or substantial change completion, if a useful candidate exists, present a compact recommendation:

@@ -20,12 +20,25 @@ Skip it for routine, small, reversible, or unambiguous work.
 
 State current behavior, purpose, constraints, unknowns, and affected risks. Separate facts from assumptions. Stop here.
 
+When genuinely competing approaches exist, keep exploration findings shared across all of them — do not re-run the same investigation once per option. Branch only in Design, where tradeoffs actually differ.
+
 ## Design
 
 Compare credible options, select an approach, name the remaining decision, and state verification and rollback where genuinely needed.
 
 If regulatory guidance applies, read only the specific knowledge needed and note traceability, validation impact, and requirement linkage. Do not invent compliance language.
 
+## Structure (optional)
+
+For a design with real architectural impact — several files or components that must change together — answer before detailed planning:
+
+- What are the major implementation units?
+- How do they depend on each other?
+- What changes together, and what must stay separate?
+- What order makes verification possible at each step?
+
+Skip this for a design that's already one clear unit of work; go straight to Implement.
+
 ## Approve
 
 State the decision plainly and wait before implementing. An explicit prior instruction that resolves it is approval.

@@ -0,0 +1,12 @@
+# <Change title>: structure
+
+## Implementation units
+
+| Unit | Depends on | Changes together with |
+|---|---|---|
+
+## Verification order
+
+1.
+
+## Seams that must stay separate
@@ -10,3 +10,4 @@ LEARN.md
 LOCAL.md
 ROOT_INTEGRATION.md
 REFERENCE_INTEGRATION.md
+ARTIFACTS.md
@@ -1 +1 @@
-1.0.0
+1.1.0
@@ -13,6 +13,7 @@ Learning & Ownership and Optional Risk Lenses add guidance without becoming a se
 5. During implementation, reinforce understanding when useful without turning the task into a lesson.
 6. Use `structured-change` alongside the active route only for one consequential, ambiguous, or regulated change.
 7. Read configuration documents only when configuration matters.
+8. Use `ARTIFACTS.md` for optional reasoning-artifact vocabulary when making current understanding materially clearer.
 
 ## Learning behavior
 

@@ -0,0 +1,62 @@
+# Learning and reasoning artifacts
+
+Optional vocabulary for making reasoning explicit. These are not mandatory
+workflow stages — a trivial task produces none of them, a consequential
+task might produce two or three.
+
+## Types
+
+- **question** — a specific thing that needs an answer before proceeding.
+- **research** — what is true today, established from evidence.
+- **model** — current understanding of a system: components, relationships,
+  ownership, invariants, evidence, unknowns. See "Model" below.
+- **design** — what should change, and why.
+- **structure** — the major implementation units for a design and how they
+  depend on each other. See "Structure" below.
+- **plan** — file-level or step-level execution order.
+- **verification** — what was checked and how.
+- **learning** — a durable insight worth persisting (see
+  `learning-closure`).
+
+## Artifact rule
+
+Create an artifact when making the reasoning explicit materially improves
+correctness, communication, or future reuse. Do not create one merely
+because the framework has a place to put it. A trivial fix produces zero
+artifacts. An unfamiliar, consequential change might produce a `model` and
+a `design`; it doesn't need all eight types.
+
+## Model
+
+Use when accumulated understanding is worth exposing so the user can
+correct it before more reasoning builds on top of it. Keep it inline in the
+conversation unless the work is meaningful enough for
+`agentic-flow/LOCAL.md` continuity.
+
+```text
+Current model:
+    <components and relationships, as a short flow or list>
+
+Evidence:
+    <files, tests, or configuration establishing this>
+
+Unknown:
+    <the highest-value open question>
+```
+
+Do not let a model accumulate unbounded state. If it stops fitting in a
+few lines, it has stopped being "current understanding" and started being
+documentation — move stable parts to `learning-flow/MAP.md` through the
+normal promotion threshold in `LOCAL.md`, and keep only what's still live.
+
+## Structure
+
+Use only inside `structured-change`, between Design and Implement, for a
+design with real architectural impact. See
+`.agents/skills/structured-change/SKILL.md`.
+
+## Refining an artifact
+
+If the user challenges a `model` or `design`, update it in place instead
+of restarting the task. See "Human correction propagation" in
+`agentic-flow/LOCAL.md`.
@@ -34,6 +34,17 @@ When a session reaches a natural stopping point:
 
 At the start of a continuing session, read only relevant history and recent session state. Do not load the entire archive by default.
 
+## Correction propagation
+
+When the user corrects a current model, a design assumption, or a proposal's premise, update that understanding in place rather than only adjusting the immediate response:
+
+1. state the previous understanding in one line;
+2. state the correction;
+3. state what it changes about the design, plan, or recommendation already given;
+4. if a `.local/` session or `learning-flow/` record already reflects the old understanding, update it — do not leave a stale record next to a corrected conversation.
+
+Do not silently keep reasoning about the corrected point as if nothing changed. Do not re-litigate a correction the user has already made.
+
 ## Safety and dignity
 
 Do not infer or persist diagnoses, sensitive emotional state, health information, identity attributes, secrets, customer data, raw production evidence, or private organizational conflict.

@@ -61,6 +61,7 @@ New evidence can change the route mid-task; this is a set of behavioral rules, n
 | `LOCAL.md` | private learning continuity and deliberate promotion |
 | `ROOT_INTEGRATION.md` | connecting existing or missing root instructions |
 | `REFERENCE_INTEGRATION.md` | extracting value from another source |
+| `ARTIFACTS.md` | optional vocabulary for explicit reasoning outputs |
 | `LEARN.md` + learning skills | understanding the effective harness and building knowledge |
 
 <details>

@@ -2,7 +2,7 @@
 
 ## Priority and scope
 
-Follow repository-native instructions and `agentic-flow/AGENTS.md` first. General collaboration, approvals, validation depth, records, and handoff belong to `agentic-flow/`.
+Follow repository-native instructions and `agentic-flow/AGENTS.md` first. General collaboration, approvals, validation, records, and handoff belong to `agentic-flow/`.
 
 This file governs learning-oriented repository work. Every selected learning skill reads and applies `agentic-flow/EDUCATION.md` selectively.
 
@@ -26,6 +26,8 @@ Do not load all skills. Do not use `agentic-workflow` as a second engineering pr
 Locate → Reason → Try or Work → Verify → Explain → Transfer
 ```
 
+Each pass through Locate–Reason can be one small round: one question, the evidence for it, the resulting understanding, then continue or stop. Stop as soon as the current understanding is sufficient for the task — do not plan the full investigation up front.
+
 - Locate the real system, outcome, boundary, governing rule, representative path, and proof surface.
 - Reason from an explicit invariant, contract, hypothesis, valid analogue, or safe seam.
 - Use the smallest responsible attempt, investigation, or change.

@@ -62,6 +62,7 @@ Select only the questions that matter:
 - Use safe trial and error when a small attempt can narrow the model.
 - Invite at most one prediction, trace, or explain-back when consequential.
 - Encourage questioning generated output, documentation, tests, and authority with evidence.
+- Prefer one small round (question → evidence → understanding → continue-or-stop) over planning the entire investigation before starting.
 - Fold only useful learning into the normal handoff.
 - Close meaningful sessions through `agentic-flow/LOCAL.md`.
 - Promote to `MAP.md` or `TAKEAWAYS.md` only when the persistence threshold is met.
@@ -14,6 +14,8 @@ Read `agentic-flow/EDUCATION.md` through the selected learning skill and only th
 Locate → Reason → Work → Verify → Explain → Transfer
 ```
 
+Each pass through Locate–Reason can be one small round: one question, the evidence for it, the resulting understanding, then continue or stop. Stop as soon as the current understanding is sufficient for the task — do not plan the full investigation up front.
+
 1. Locate the relevant business, scientific, human, physical, domain, or technical system.
 2. Identify the outcome, boundary, rule or invariant, representative path, and proof surface.
 3. Investigate or work through the smallest responsible route.

@@ -10,7 +10,8 @@ cases:
     must_not: [treat learning-flow as universal execution policy]
   - prompt: Fix this obvious typo quickly. The settings file still uses defaults.
     expected_skill: none_or_task_skill
-    must_include: [use balanced preset, no questionnaire, proportionate verification]
+    must_include: [use balanced preset, no questionnaire, proportionate verification, zero artifacts]
+    must_not: [create a model artifact, narrate artifact creation]
   - prompt: This change has two credible public API shapes and repository evidence does not select one.
     expected_behavior: ask_one_consequential_product_question
     must_include: [meaningful fork, concise options]
@@ -125,3 +126,10 @@ cases:
     expected_behavior: inspect_before_asking
     must_include: [inspect existing ownership and validation conventions, use repository evidence if decisive, explain the decision from evidence]
     must_not: [ask the user unnecessarily, invent a product preference]
+
+  - prompt: >
+      You said OrderService submits directly to the ERP. That's wrong — submission actually
+      happens in a queue worker. Update your model and tell me what that changes.
+    expected_behavior: correction_propagation
+    must_include: [acknowledge previous understanding, state the correction, state what it changes about the prior recommendation]
+    must_not: [ignore the correction, restate the old model, re-ask a question the correction already answered]
@@ -46,5 +46,9 @@ cases:
     must_not: [tracked contributor state, private shared detail, uncertain promotion]
   - prompt: Fix this obvious typo and move on quickly.
     expected_primary_skill: none_or_normal_engineering
-    must_include: [no learning artifact, no understanding check]
-    must_not: [resilience ceremony, domain ownership questionnaire]
+    must_include: [no learning artifact, no understanding check, zero artifacts]
+    must_not: [resilience ceremony, domain ownership questionnaire, create a model]
+  - prompt: Work through an unfamiliar subsystem in focused rounds until the current task is resolved.
+    expected_primary_skill: selected_task_learning_skill
+    must_include: [one question, evidence, resulting understanding, continue-or-stop, stop when sufficient]
+    must_not: [plan the entire investigation up front, keep investigating after resolution]
@@ -19,3 +19,8 @@ cases:
     expected_skill: learning-freshness
     must_include: [external source, retained provenance, external revalidation]
     must_not: [claim internal code proves the external source]
+
+  - prompt: This session learned a new fact and also corrected a stale takeaway in learning-flow/TAKEAWAYS.md. Decide what to capture.
+    expected_skill: learning-closure
+    must_include: [changed understanding, stale existing entry, flag update in same closure pass, evidence]
+    must_not: [only propose a new fact, leave the known-stale entry for later freshness checking]
@@ -28,10 +28,11 @@ cases:
     must_include: [intended use, compact system model, boundaries, representative path, evidence, human control point when relevant]
   - prompt: Make this one-line mechanical edit quickly.
     expected_skill: optional
-    must_include: [no quiz, no persistent artifact]
-    must_not: [pretend safety case, domain ceremony]
+    must_include: [no quiz, no persistent artifact, zero artifacts]
+    must_not: [pretend safety case, domain ceremony, create a model]
   - prompt: Save everything we discussed as learning notes.
     expected_skill: repository-learning
+    expected_branch: orientation
     must_include: [complete private state under .local, promote only verified reusable takeaways]
     must_not: [tracked transcript, tracked person-specific folder, uncertain shared claim]
   - prompt: Configure how agents should plan and pause in this repository.
@@ -48,3 +49,8 @@ cases:
     expected_branch: orientation
     must_include: [domain slice, representative path, proof entry point]
     must_not: [agentic setup status write, framework inventory, separate recap section]
+  - prompt: Learn this unfamiliar subsystem only as far as needed to fix the current issue.
+    expected_skill: repository-learning
+    expected_branch: orientation
+    must_include: [one small round, question, evidence, understanding, continue-or-stop, stop when sufficient]
+    must_not: [plan the entire investigation up front, continue investigating after the task is resolved]
@@ -54,3 +54,18 @@ cases:
     expected_behavior: extension_is_additive
     must_include: [same minimal or full profile behavior, lens applies only when the change is validated safety-relevant or audited, agents assist humans decide]
     must_not: [every commit now requires regulatory sign-off, extension changes what the profile means]
+
+  - prompt: Make ERP submission idempotent across the service, the queue worker, and the retry client.
+    expected_skill: structured-change
+    must_include: [shared exploration, Structure section before file-level detail, implementation units, dependencies, verification order]
+    must_not: [repeat the same repository investigation for each option, jump directly from Design to file list]
+
+  - prompt: Add a single validation helper in one file using structured-change.
+    expected_behavior: skip_structure
+    must_include: [single clear unit, skip Structure, proceed to Implement]
+    must_not: [Structure section, implementation-unit table]
+
+  - prompt: We have two credible approaches for ERP retries. Compare them after inspecting the shared retry and idempotency behavior.
+    expected_skill: structured-change
+    must_include: [shared repository facts inspected once, options branch in Design, tradeoffs]
+    must_not: [duplicate investigation for each option]