diff --git a/MANIFEST.txt b/MANIFEST.txt index 6d372db..59fb4cd 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -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,7 +78,7 @@ 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 @@ -84,12 +86,12 @@ 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 diff --git a/docs/EXAMPLE_WALKTHROUGH.md b/docs/EXAMPLE_WALKTHROUGH.md index c161f4a..388b59f 100644 --- a/docs/EXAMPLE_WALKTHROUGH.md +++ b/docs/EXAMPLE_WALKTHROUGH.md @@ -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 diff --git a/sample/common/.agents/skills/learning-closure/SKILL.md b/sample/common/.agents/skills/learning-closure/SKILL.md index 0fb8016..c245fdc 100644 --- a/sample/common/.agents/skills/learning-closure/SKILL.md +++ b/sample/common/.agents/skills/learning-closure/SKILL.md @@ -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: diff --git a/sample/common/.agents/skills/structured-change/SKILL.md b/sample/common/.agents/skills/structured-change/SKILL.md index e5dc134..6721454 100644 --- a/sample/common/.agents/skills/structured-change/SKILL.md +++ b/sample/common/.agents/skills/structured-change/SKILL.md @@ -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. diff --git a/sample/common/.agents/skills/structured-change/templates/structure.md b/sample/common/.agents/skills/structured-change/templates/structure.md new file mode 100644 index 0000000..0878b4c --- /dev/null +++ b/sample/common/.agents/skills/structured-change/templates/structure.md @@ -0,0 +1,12 @@ +# : structure + +## Implementation units + +| Unit | Depends on | Changes together with | +|---|---|---| + +## Verification order + +1. + +## Seams that must stay separate diff --git a/sample/common/agentic-flow/.managed-files b/sample/common/agentic-flow/.managed-files index 161d0fe..d64a205 100644 --- a/sample/common/agentic-flow/.managed-files +++ b/sample/common/agentic-flow/.managed-files @@ -10,3 +10,4 @@ LEARN.md LOCAL.md ROOT_INTEGRATION.md REFERENCE_INTEGRATION.md +ARTIFACTS.md diff --git a/sample/common/agentic-flow/.template-version b/sample/common/agentic-flow/.template-version index 3eefcb9..9084fa2 100644 --- a/sample/common/agentic-flow/.template-version +++ b/sample/common/agentic-flow/.template-version @@ -1 +1 @@ -1.0.0 +1.1.0 diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index 5b6e5c8..089eefa 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -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 diff --git a/sample/common/agentic-flow/ARTIFACTS.md b/sample/common/agentic-flow/ARTIFACTS.md new file mode 100644 index 0000000..87df2b7 --- /dev/null +++ b/sample/common/agentic-flow/ARTIFACTS.md @@ -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: + + +Evidence: + + +Unknown: + +``` + +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`. diff --git a/sample/common/agentic-flow/LOCAL.md b/sample/common/agentic-flow/LOCAL.md index 65ee010..ec6cd9b 100644 --- a/sample/common/agentic-flow/LOCAL.md +++ b/sample/common/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. diff --git a/sample/common/agentic-flow/README.md b/sample/common/agentic-flow/README.md index de5c60f..272aa70 100644 --- a/sample/common/agentic-flow/README.md +++ b/sample/common/agentic-flow/README.md @@ -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 |
diff --git a/sample/profiles/full/learning-flow/AGENTS.md b/sample/profiles/full/learning-flow/AGENTS.md index 2af915c..5e52945 100644 --- a/sample/profiles/full/learning-flow/AGENTS.md +++ b/sample/profiles/full/learning-flow/AGENTS.md @@ -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. diff --git a/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md b/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md index 7ee9cc9..92c8cc6 100644 --- a/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md +++ b/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md @@ -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. diff --git a/sample/profiles/minimal/learning-flow/AGENTS.md b/sample/profiles/minimal/learning-flow/AGENTS.md index e07d319..3da9548 100644 --- a/sample/profiles/minimal/learning-flow/AGENTS.md +++ b/sample/profiles/minimal/learning-flow/AGENTS.md @@ -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. diff --git a/skill-evals/agentic-cases.yaml b/skill-evals/agentic-cases.yaml index e1b1b1a..c4abf4e 100644 --- a/skill-evals/agentic-cases.yaml +++ b/skill-evals/agentic-cases.yaml @@ -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] diff --git a/skill-evals/full-cases.yaml b/skill-evals/full-cases.yaml index 9da8c3b..816081e 100644 --- a/skill-evals/full-cases.yaml +++ b/skill-evals/full-cases.yaml @@ -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] diff --git a/skill-evals/learning-lifecycle-cases.yaml b/skill-evals/learning-lifecycle-cases.yaml index eea794f..5bec51c 100644 --- a/skill-evals/learning-lifecycle-cases.yaml +++ b/skill-evals/learning-lifecycle-cases.yaml @@ -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] diff --git a/skill-evals/minimal-cases.yaml b/skill-evals/minimal-cases.yaml index 4624dff..b5362db 100644 --- a/skill-evals/minimal-cases.yaml +++ b/skill-evals/minimal-cases.yaml @@ -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] diff --git a/skill-evals/structured-change-cases.yaml b/skill-evals/structured-change-cases.yaml index 282a83b..0b8c451 100644 --- a/skill-evals/structured-change-cases.yaml +++ b/skill-evals/structured-change-cases.yaml @@ -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]