From f3839183fc2a3c5f70aa223afc2381b7d6036033 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Barnab=C3=A1s=20Gell=C3=A9r?= Date: Mon, 10 Aug 2026 14:44:30 +0200 Subject: [PATCH] chore: simplify various skills and flow patterns --- CHANGELOG.md | 21 ++++++ MANIFEST.txt | 65 ++++++++----------- README.md | 2 +- docs/ARCHITECTURE.md | 25 +++++++ docs/DESIGN_NOTES.md | 20 +++++- .../skills/learning-freshness/SKILL.md | 2 +- .../.agents/skills/structured-change/SKILL.md | 2 + sample/common/agentic-flow/.managed-files | 1 - sample/common/agentic-flow/.template-version | 2 +- sample/common/agentic-flow/AGENTS.md | 2 +- sample/common/agentic-flow/ARTIFACTS.md | 62 ------------------ sample/common/agentic-flow/README.md | 1 - sample/common/agentic-flow/WORKFLOW.md | 19 ++++++ .../.agents/skills/analogous-feature/SKILL.md | 21 ------ .../skills/challenge-debugging/SKILL.md | 22 ------- .../templates/challenge.md | 28 -------- .../skills/learning-bootstrap/SKILL.md | 2 +- .../skills/repository-orientation/SKILL.md | 21 ------ .../.agents/skills/safe-refactor/SKILL.md | 22 ------- .../skills/ticket-learning-path/SKILL.md | 2 +- .../full/learning-flow/.managed-files | 3 - .../full/learning-flow/.managed-skills | 5 +- .../full/learning-flow/.template-version | 2 +- sample/profiles/full/learning-flow/AGENTS.md | 35 ++++++++-- .../profiles/full/learning-flow/BOOTSTRAP.md | 43 ------------ .../profiles/full/learning-flow/PLAYBOOKS.md | 18 ----- sample/profiles/full/learning-flow/README.md | 17 ++--- .../learning-flow/UNDERSTANDING_CHECKS.md | 49 -------------- skill-evals/full-cases.yaml | 10 +-- 29 files changed, 160 insertions(+), 364 deletions(-) delete mode 100644 sample/common/agentic-flow/ARTIFACTS.md delete mode 100644 sample/profiles/full/.agents/skills/analogous-feature/SKILL.md delete mode 100644 sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md delete mode 100644 sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md delete mode 100644 sample/profiles/full/.agents/skills/repository-orientation/SKILL.md delete mode 100644 sample/profiles/full/.agents/skills/safe-refactor/SKILL.md delete mode 100644 sample/profiles/full/learning-flow/BOOTSTRAP.md delete mode 100644 sample/profiles/full/learning-flow/PLAYBOOKS.md delete mode 100644 sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md diff --git a/CHANGELOG.md b/CHANGELOG.md index cd27a12..26aa9b2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,10 +2,31 @@ ## Unreleased +Architectural simplification of the `full` profile: reduced meta-ceremony while preserving every behavior the framework depends on (repository authority, selective learning, hypothesis-first proposals, consequential-change reasoning, private continuity, optional regulatory guidance). + ### Added +- `full` profile `repository-learning` skill: one skill covering orientation, bug, feature, and refactor branches, matching the shape the minimal profile already used. Carries all the depth of the four skills it replaces (ownership-compass questions, per-branch report shape, optional `challenge.md` template). +- "Making reasoning explicit" section in `agentic-flow/WORKFLOW.md`, replacing `ARTIFACTS.md` with just the one artifact type (the compact current-understanding model) that had independent operational value. +- "Branches" fallback table inline in `full/learning-flow/AGENTS.md`, for agents without task-skill support, replacing `PLAYBOOKS.md`. +- Collapsible "Check techniques and handling" section under `full/learning-flow/AGENTS.md`'s "Understanding checks" heading, replacing `UNDERSTANDING_CHECKS.md`. +- Explicit reference to `structured-change`'s own `knowledge/engineering/` folder from its Design step; the folder previously existed but was never read by the skill that owns it. +- "Runtime instruction flow" diagram in `docs/ARCHITECTURE.md` showing the actual per-task instruction path end to end. + +### Removed + +- `agentic-flow/ARTIFACTS.md` (six of its eight artifact types restated concepts already owned by `structured-change`, `WORKFLOW.md`, or `learning-closure`). +- `full/learning-flow/BOOTSTRAP.md` (duplicated the `learning-bootstrap` skill's procedure almost verbatim; the skill is now the sole owner). +- `full/learning-flow/PLAYBOOKS.md` (duplicated four skills' branch logic; content now lives inline in `AGENTS.md`). +- `full/learning-flow/UNDERSTANDING_CHECKS.md` (restated a rule already stated in four other files). +- `full` profile skills `repository-orientation`, `challenge-debugging`, `analogous-feature`, `safe-refactor` (merged into `repository-learning`). + ### Changed +- Deduplicated the external-source provenance field list between `learning-closure` and `learning-freshness`; `learning-closure` is now the single owner. +- `full/learning-flow/README.md` diagram and "Understanding and assessment" section updated to match the reduced skill count and single canonical rule. +- `ticket-learning-path`'s implementation-handoff step now names `repository-learning` instead of the three merged skills. + ## 1.1.0 Finalized the post-1.0 learning and reasoning improvements for the 1.1.0 release. diff --git a/MANIFEST.txt b/MANIFEST.txt index dc54496..7de62e5 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -1,10 +1,14 @@ .gitattributes 40 .gitignore 324 AGENTS.md 2995 -CHANGELOG.md 21735 +CHANGELOG.md 24247 +LICENSE 2213 +README.md 8952 +adoption/ADOPT.md 4177 +adoption/README.md 2057 docs/AGENTIC_WORKFLOW_SANITY.md 9207 -docs/ARCHITECTURE.md 5689 -docs/DESIGN_NOTES.md 31204 +docs/ARCHITECTURE.md 7131 +docs/DESIGN_NOTES.md 35837 docs/EDUCATION_MODEL.md 5452 docs/INITIALIZE_LEARNING_FLOW.md 10880 docs/README.md 4016 @@ -15,11 +19,13 @@ docs/references/REFERENCE_REVIEW_GOOSE.md 2486 docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md 9505 docs/references/REFERENCE_REVIEW_LITT.md 2069 docs/references/REFERENCE_REVIEW_POCOK.md 2155 -LICENSE 2213 -README.md 8888 +sample/README.md 2997 sample/common/.agents/skills/agentic-workflow/SKILL.md 2686 -sample/common/.agents/skills/learn-anything/agents/openai.yaml 246 sample/common/.agents/skills/learn-anything/SKILL.md 1756 +sample/common/.agents/skills/learn-anything/agents/openai.yaml 246 +sample/common/.agents/skills/learning-closure/SKILL.md 3605 +sample/common/.agents/skills/learning-freshness/SKILL.md 1908 +sample/common/.agents/skills/structured-change/SKILL.md 3059 sample/common/.agents/skills/structured-change/knowledge/engineering/ai-collaboration.md 2533 sample/common/.agents/skills/structured-change/knowledge/engineering/architecture.md 1386 sample/common/.agents/skills/structured-change/knowledge/engineering/dependency-management.md 1300 @@ -27,26 +33,25 @@ 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 2770 sample/common/.agents/skills/structured-change/templates/design.md 649 sample/common/.agents/skills/structured-change/templates/exploration.md 368 sample/common/.agents/skills/structured-change/templates/structure.md 243 -sample/common/agentic-flow/.managed-files 183 +sample/common/agentic-flow/.managed-files 170 sample/common/agentic-flow/.managed-skills 86 sample/common/agentic-flow/.template-version 6 -sample/common/agentic-flow/AGENTS.md 5961 -sample/common/agentic-flow/ARTIFACTS.md 2605 +sample/common/agentic-flow/AGENTS.md 5995 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 4179 -sample/common/agentic-flow/README.md 2969 +sample/common/agentic-flow/README.md 2897 sample/common/agentic-flow/REFERENCE_INTEGRATION.md 2183 sample/common/agentic-flow/ROOT_INTEGRATION.md 3086 sample/common/agentic-flow/SETTINGS.md 544 -sample/common/agentic-flow/WORKFLOW.md 5020 +sample/common/agentic-flow/WORKFLOW.md 6059 sample/common/local/learning-history.md 1528 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md 3530 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/audit-trails.md 1444 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/cfr-part-11-overview.md 2336 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/change-control.md 1447 @@ -59,33 +64,24 @@ sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regul sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/risk-management.md 1873 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/traceability.md 1871 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/validation.md 1609 -sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md 3530 sample/extensions/regulatory/learning-flow/.extension-managed-files 81 sample/extensions/regulatory/learning-flow/.extension-managed-skills 21 sample/extensions/regulatory/learning-flow/.extension-name 11 sample/extensions/regulatory/learning-flow/REGULATORY.md 1882 -sample/profiles/full/.agents/skills/analogous-feature/SKILL.md 1408 -sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md 1426 -sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md 511 sample/profiles/full/.agents/skills/change-explainer/SKILL.md 1308 sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md 353 -sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md 1522 -sample/profiles/full/.agents/skills/repository-orientation/SKILL.md 1222 -sample/profiles/full/.agents/skills/safe-refactor/SKILL.md 1373 -sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md 1519 +sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md 1491 +sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md 1513 sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md 405 -sample/profiles/full/learning-flow/.managed-files 137 -sample/profiles/full/learning-flow/.managed-skills 132 +sample/profiles/full/learning-flow/.managed-files 87 +sample/profiles/full/learning-flow/.managed-skills 77 sample/profiles/full/learning-flow/.template-profile 5 sample/profiles/full/learning-flow/.template-version 6 -sample/profiles/full/learning-flow/AGENTS.md 4716 -sample/profiles/full/learning-flow/BOOTSTRAP.md 1788 +sample/profiles/full/learning-flow/AGENTS.md 6548 sample/profiles/full/learning-flow/MAP.md 1464 -sample/profiles/full/learning-flow/PLAYBOOKS.md 1327 -sample/profiles/full/learning-flow/README.md 2574 +sample/profiles/full/learning-flow/README.md 2320 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 3718 sample/profiles/minimal/learning-flow/.managed-files 87 sample/profiles/minimal/learning-flow/.managed-skills 20 @@ -95,22 +91,17 @@ 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 -sample/README.md 2997 sample/root/AGENTS.md 2102 sample/root/AGENTS.pointer.md 551 +scripts/README.md 6771 scripts/install.bat 1477 scripts/install.ps1 40236 scripts/install.sh 34910 -scripts/README.md 6771 +skill-evals/README.md 1667 +skill-evals/adoption-cases.yaml 1337 skill-evals/agentic-cases.yaml 8895 skill-evals/conversation-cases.yaml 3653 -skill-evals/full-cases.yaml 4640 +skill-evals/full-cases.yaml 4648 +skill-evals/learning-lifecycle-cases.yaml 1599 skill-evals/minimal-cases.yaml 3655 -skill-evals/README.md 1667 skill-evals/structured-change-cases.yaml 4710 -adoption/ADOPT.md 4177 -adoption/README.md 2057 -sample/common/.agents/skills/learning-closure/SKILL.md 3605 -sample/common/.agents/skills/learning-freshness/SKILL.md 1904 -skill-evals/learning-lifecycle-cases.yaml 1599 -skill-evals/adoption-cases.yaml 1337 diff --git a/README.md b/README.md index 0bdbde8..b168af9 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ When relevant: | Profile | Learning surface | |---|---| | `minimal` | one compact repository-learning skill | -| `full` | focused orientation, debugging, feature, refactor, and explanation skills | +| `full` | deeper `repository-learning` skill (orientation, debugging, feature, refactor), plus baseline, ticket-path, and change-explanation skills | Both use the same common educational constitution and agentic layer. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2856b64..691c065 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -116,6 +116,31 @@ This separation is a trust and context boundary as well as an installation bound +## Runtime instruction flow + +The path an agent actually walks for one task, independent of profile: + +```mermaid +flowchart TD + Root[Repository-native instructions] --> AF[agentic-flow/AGENTS.md] + AF --> Route{Task needs repository
learning support?} + Route -->|no| WF[WORKFLOW.md loop] + Route -->|yes| LF[learning-flow/AGENTS.md] + Route -->|general topic, no repo| LA[learn-anything] + LF --> Skill[One learning skill:
bootstrap / repository-learning branch /
change-explainer / ticket-learning-path] + Skill --> WF + WF --> Sig{Consequential, ambiguous,
or regulated?} + Sig -->|yes| SC["structured-change
(+ regulatory-knowledge if installed)"] + Sig -->|no| Act[Act → Verify] + SC --> Act + Act --> HO[Handoff] + HO --> Reuse{Reusable insight?} + Reuse -->|yes| LC[learning-closure →
LOCAL.md / MAP.md / TAKEAWAYS.md] + Reuse -->|no| Done[Done] +``` + +Every box is read only when its condition is met; `EDUCATION.md` is applied selectively inside whichever learning skill runs, not as a separate stop. A maintainer auditing "what does an installed `full` profile actually load for a bug fix" reads this diagram top to bottom: `AGENTS.md` → `learning-flow/AGENTS.md` → `repository-learning` (Bug branch) → `WORKFLOW.md` → optionally `structured-change` → handoff → optionally `learning-closure`. No other file sits on that path unless the task specifically needs it. + ## Learning lifecycle Learning is treated as a lifecycle rather than a second engineering process: diff --git a/docs/DESIGN_NOTES.md b/docs/DESIGN_NOTES.md index 574a2be..d6e4b06 100644 --- a/docs/DESIGN_NOTES.md +++ b/docs/DESIGN_NOTES.md @@ -158,6 +158,22 @@ The rest of the pass fit the same "one canonical owner" discipline as everything A larger set of proposed improvements (lightweight learning artifacts, incremental learning rounds, an explicit inspectable system model, a structure step between design and planning, branching alternative designs) was reviewed and deliberately deferred rather than folded in. Each would require real design and evaluation work to avoid becoming ceremony, which is exactly what this document's "smallest coherent hardening pass" standard rules out for a single pass; the reasoning and file-level implementation detail for each lives in the post-1.0 backlog document delivered alongside this release, not inside this repository, so an optional future improvement doesn't read as a committed roadmap. +## v1.1 remove meta-ceremony + +A consumer-perspective review of an installed `full` profile found that correctness had come to depend on keeping many documents synchronized: a competent developer had to discover and cross-reference more instruction surfaces than the underlying engineering task justified. Five duplications accounted for most of the cost, each fixed by giving the behavior exactly one owner instead of shortening the copies: + +- `agentic-flow/ARTIFACTS.md` named eight "artifact types," six of which restated concepts `structured-change`, `WORKFLOW.md`, or `learning-closure` already owned, and its correction-propagation guidance only pointed at `LOCAL.md` anyway. The one artifact type with real, undocumented-elsewhere behavior — the compact current-understanding `model` — moved into a "Making reasoning explicit" section in `agentic-flow/WORKFLOW.md`. The file was removed. +- `full/learning-flow/BOOTSTRAP.md` and the `learning-bootstrap` skill contained the same nine-step procedure almost verbatim. The root-level file was removed; the skill is now the single, self-contained owner. +- `full/learning-flow/PLAYBOOKS.md` existed only as a fallback for agents without task-skill support, and duplicated the branch logic of four separate skills in table form. That fallback content now lives inline in `full/learning-flow/AGENTS.md` under "Branches" — the file every setup reads regardless of skill support — so the separate file added a synchronization cost without adding reach. It was removed. +- `full/learning-flow/UNDERSTANDING_CHECKS.md` restated a rule ("ask at most one check; confidence is not proof") already stated in `EDUCATION.md`, `agentic-flow/AGENTS.md`, `full/learning-flow/AGENTS.md`, and `full/learning-flow/README.md`. The elaboration it added beyond the rule (check techniques, when to skip, how to handle a wrong answer) moved into a collapsible section under `full/learning-flow/AGENTS.md`'s existing "Understanding checks" heading; the other three surfaces now state the rule once and point there instead of restating it. +- `structured-change`'s own `knowledge/engineering/` folder was never referenced by its own `SKILL.md` — a genuinely orphaned surface, not a duplicated one. The Design step now names it explicitly. + +Separately, the full profile's seven near-identical task skills (`learning-bootstrap`, `repository-orientation`, `challenge-debugging`, `analogous-feature`, `safe-refactor`, `change-explainer`, `ticket-learning-path`) reversed the v1.0-era "progressive disclosure" framing (see "Skill routing" above, then current): `repository-orientation`, `challenge-debugging`, `analogous-feature`, and `safe-refactor` shared the same header, the same locate-reason-verify-report shape, and the same PLAYBOOKS.md table row each — the disclosure was one of file count, not of actual content boundaries. They merged into one `repository-learning` skill with four branches, matching the shape the minimal profile already used successfully for the same four concerns, with full's extra depth (the ownership-compass questions, deeper proof-by-risk requirements, and the optional `challenge.md` template) preserved inside it. `learning-bootstrap`, `change-explainer`, and `ticket-learning-path` remain separate because each has a genuinely distinct trigger moment and non-duplicated content — merging them would have hidden that distinction rather than removed real duplication. + +`learning-closure` and `learning-freshness` were reviewed against the same test and kept separate: each is already lean, each fires at a different point in the workflow (handoff vs. deliberate maintenance), and separate descriptions help an agent's skill matching select the right one. Only their duplicated external-source provenance field list was deduplicated, with `learning-closure` as the single owner. `LOCAL.md` and `structured-change` were reviewed and kept as-is: both are load-bearing, cross-referenced from nearly every skill, and not redundant with anything else in the repository. + +Net effect for a `full`-profile consumer: a typical task now touches four fewer files to discover the right procedure, and the rule "ask at most one understanding check" has one canonical statement instead of four. No behavior the framework depends on for repository-specific authority, selective learning, hypothesis-first proposals, consequential-change reasoning, private continuity, or optional regulatory guidance changed. + ## General agentic loop ```text @@ -187,7 +203,7 @@ Designed for daily use and token economy. Its shared tracked learning is limited ### Full -Designed for deliberate onboarding and long-lived learning programs. It keeps only maps, takeaways, repository baselines, and task-specific learning skills tracked by default. Private sessions and contributor-specific template instances use `.local/`; promoted shared artifacts remain exceptional. Optional challenge, ticket-path, and change-explainer templates live inside their owning skills and are materialized only on explicit need. +Designed for deliberate onboarding and long-lived learning programs. It keeps only maps, takeaways, repository baselines, and task-specific learning skills tracked by default. Private sessions and contributor-specific template instances use `.local/`; promoted shared artifacts remain exceptional. An optional challenge template lives inside `repository-learning`; ticket-path and change-explainer templates live inside their own owning skills. All are materialized only on explicit need. ## Shared learning loop @@ -227,7 +243,7 @@ Conversation is the live interaction layer. `.local/` is the private continuity The common `agentic-workflow` skill initializes, configures, explains, or reviews the workflow. It is not loaded as a second engineering procedure during an ordinary task. The separate common `learn-anything` skill owns general learning conversations and does not inspect the repository by default. The common `structured-change` skill elaborates `Decide` for one consequential, ambiguous, or regulated change; it runs alongside the active route, not instead of it, and most tasks never touch it. The `regulatory` extension's `regulatory-knowledge` skill is reference material `structured-change` and task skills consult, not a workflow of its own. -The full learning profile keeps seven narrow repository skills for progressive disclosure, but one skill owns the current task. The minimal profile uses one `repository-learning` skill with compact branches for bug, feature, refactor, and orientation work. Both add the common generic conversation skill without changing their repository-learning profile. +The full learning profile uses one deeper `repository-learning` skill covering four branches (orientation, bug, feature, refactor) plus `learning-bootstrap`, `change-explainer`, and `ticket-learning-path` for their distinct trigger moments. The minimal profile uses the same `repository-learning` shape with compact branches and no baseline, explainer, or ticket-path skills. Both add the common generic conversation skill without changing their repository-learning profile. ## Installer lifecycle diff --git a/sample/common/.agents/skills/learning-freshness/SKILL.md b/sample/common/.agents/skills/learning-freshness/SKILL.md index a10bfb7..fff5f2e 100644 --- a/sample/common/.agents/skills/learning-freshness/SKILL.md +++ b/sample/common/.agents/skills/learning-freshness/SKILL.md @@ -36,7 +36,7 @@ Reuse existing repository evidence before broad rescanning. If a claim depends on material outside the repository, do not mark it verified from repository inspection alone. -Use retained provenance such as URL, revision/version, publication date, access date, and relevant section to identify what must be rechecked externally. +Use the retained provenance fields `learning-closure` records (source, revision, published, accessed, section) to identify what must be rechecked externally. If external access is unavailable, report the claim as externally sourced and not revalidated. diff --git a/sample/common/.agents/skills/structured-change/SKILL.md b/sample/common/.agents/skills/structured-change/SKILL.md index 51b9f92..1886133 100644 --- a/sample/common/.agents/skills/structured-change/SKILL.md +++ b/sample/common/.agents/skills/structured-change/SKILL.md @@ -38,6 +38,8 @@ When genuinely competing approaches exist, keep exploration findings shared acro Compare credible options, select an approach, name the remaining decision, and state verification and rollback where genuinely needed. +For ordinary engineering tradeoffs (architecture, dependency management, documentation, maintainability, modernization, testing, AI-collaboration), consult the relevant file under `knowledge/engineering/` instead of reasoning from first principles. Read only the file the decision needs. + 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) diff --git a/sample/common/agentic-flow/.managed-files b/sample/common/agentic-flow/.managed-files index d64a205..161d0fe 100644 --- a/sample/common/agentic-flow/.managed-files +++ b/sample/common/agentic-flow/.managed-files @@ -10,4 +10,3 @@ 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 9084fa2..26aaba0 100644 --- a/sample/common/agentic-flow/.template-version +++ b/sample/common/agentic-flow/.template-version @@ -1 +1 @@ -1.1.0 +1.2.0 diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index 3a3a3af..374b0f4 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -13,7 +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. +8. Make current understanding explicit (see "Making reasoning explicit" in `WORKFLOW.md`) only when it materially improves correctness or communication. ## Learning behavior diff --git a/sample/common/agentic-flow/ARTIFACTS.md b/sample/common/agentic-flow/ARTIFACTS.md deleted file mode 100644 index a6faa43..0000000 --- a/sample/common/agentic-flow/ARTIFACTS.md +++ /dev/null @@ -1,62 +0,0 @@ -# Learning and reasoning artifacts - -Optional vocabulary for making reasoning explicit. These are not workflow stages. A trivial task produces none; 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. -- **design** — what should change, and why. -- **structure** — the major implementation units for a design and how they depend on each other. -- **plan** — file-level or step-level execution order. -- **verification** — what was checked and how. -- **learning** — a durable insight worth persisting. - -## Artifact rule - -Create an artifact when making reasoning explicit materially improves correctness, communication, or future reuse. Do not create one merely because the framework has a place to put it. - -```mermaid -flowchart LR - T[Task] --> Q{Does explicit reasoning help?} - Q -->|No| N[No artifact] - Q -->|Yes| S[Choose smallest useful artifact] - S --> U[Use it while live] - U --> P{Worth retaining?} - P -->|No| D[Discard] - P -->|Yes| L[Learning closure / durable owner] -``` - -A trivial fix produces zero artifacts. An unfamiliar, consequential change might produce a `model` and a `design`; it does not 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 is 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/README.md b/sample/common/agentic-flow/README.md index 5f8ff22..0d34ad2 100644 --- a/sample/common/agentic-flow/README.md +++ b/sample/common/agentic-flow/README.md @@ -61,7 +61,6 @@ 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-anything` | general-topic learning without repository inspection |
diff --git a/sample/common/agentic-flow/WORKFLOW.md b/sample/common/agentic-flow/WORKFLOW.md index 0a29f53..65cab66 100644 --- a/sample/common/agentic-flow/WORKFLOW.md +++ b/sample/common/agentic-flow/WORKFLOW.md @@ -24,6 +24,25 @@ If collaboration behavior materially affects the result and repository evidence For a change that is architecturally significant, genuinely ambiguous between credible options, or regulated, expand Decide into a short Explore → Design → Approve sequence using `structured-change` before moving to Act: state current understanding and unknowns, propose an approach with tradeoffs and a requested decision, then get explicit approval. Keep this proportional; do not expand Decide this way for ordinary work. +### Making reasoning explicit + +Write down current understanding only when doing so materially improves correctness, communication, or future reuse — not because the framework has a place to put it. A trivial fix produces nothing written; an unfamiliar, consequential change might produce one compact model. + +```text +Current model: + + +Evidence: + + +Unknown: + +``` + +Keep it inline in the conversation unless the work is meaningful enough for `LOCAL.md` continuity. Do not let it accumulate unbounded state — once 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 is still live. + +If the user challenges this model, update it in place instead of restarting the task — see "Correction propagation" in `LOCAL.md`. + ## Act Make the smallest responsible change or investigation that reaches the outcome. Keep unrelated cleanup out of scope. Do not force one-file or one-commit steps when a coherent slice is safer. diff --git a/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md b/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md deleted file mode 100644 index 1637492..0000000 --- a/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: analogous-feature -description: Implement, plan, or teach a feature by finding the nearest valid analogue and separating shared invariants from intentional differences. Use when existing behavior is the primary guide; do not copy the nearest namesake blindly. ---- - -# Analogous feature - -Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md`. Read `agentic-flow/EDUCATION.md`, `learning-flow/AGENTS.md`, and only relevant maps, tests, and canonical findings. - -1. Define the actor, intended outcome, capability, observable behavior, and governing invariants. -2. Test whether the behavior should be built or automated, and what must remain a human decision. -3. Search by behavior and evidence, not name alone. -4. Compare candidates across domain rules, data flow, configuration, interface, tests, failure effects, access, and operations. -5. Select the nearest valid analogue. -6. Separate shared invariants from intentional differences. -7. Use the smallest established extension seam. -8. Prove the reused invariant, intended difference, failure behavior, and control boundary in proportion to risk. - -Ask at most one check about why the analogue is valid or where copying it would be wrong. - -Report the selected analogue, invariant and difference table, build judgment, seam, proof, risks, controls, and deferred divergence. Do not create an abstraction merely because two features look similar. diff --git a/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md b/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md deleted file mode 100644 index 3b9d6c8..0000000 --- a/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: challenge-debugging -description: Diagnose or teach through a concrete bug, failing test, intermittent issue, or incorrect runtime behavior. Use to reproduce, narrow, explain, contain, and safely fix a symptom; do not jump to a guessed patch. ---- - -# Challenge debugging - -Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md`. Read `agentic-flow/EDUCATION.md` and `learning-flow/AGENTS.md`. Load only material for the affected territory. - -1. State the affected real-world outcome or rule, observable symptom, and falsifiable expectation. -2. Identify immediate safety, data, access, or operational containment when relevant. -3. Find the smallest discriminating reproduction, test, trace, log, or safe observation. -4. Rank credible hypotheses and test one uncertainty at a time. -5. Explain the failure mechanism before changing code. -6. Validate machine-generated and human hypotheses against decisive evidence. -7. Apply the narrowest responsible containment or fix when requested. -8. Add proportional regression evidence and name the degraded mode, fallback, or untested boundary. -9. Stop when one mechanism explains the symptom and evidence distinguishes it from credible alternatives. - -Use at most one prediction or explain-back. Do not keep a hypothesis diary. - -Report symptom, expectation, containment, decisive evidence, mechanism, fix or seam, regression proof, operational boundary, and remaining risk. diff --git a/sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md b/sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md deleted file mode 100644 index a370d33..0000000 --- a/sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md +++ /dev/null @@ -1,28 +0,0 @@ -# - -## Outcome - -## Relevant boundary and representative path - -## Behavior contract, hypothesis, or analogue - -## Work and decisive evidence - -## Optional understanding check - -_Use at most one when consequential._ - -## Reusable learning (optional) - -- **Model:** -- **Evidence:** -- **Boundary:** - -## Promotion decision - -_Keep conversational, update map/takeaways, or create a durable repository artifact. State why._ - -
-Detailed evidence and reproduction steps - -
diff --git a/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md b/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md index a628e27..ed48a78 100644 --- a/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md +++ b/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md @@ -5,7 +5,7 @@ description: Create or refresh a compact repository baseline covering the real s # Learning bootstrap -Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md` for collaboration behavior. Read `agentic-flow/EDUCATION.md`, `learning-flow/AGENTS.md`, and `learning-flow/BOOTSTRAP.md`. +Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md` for collaboration behavior. Read `agentic-flow/EDUCATION.md` and `learning-flow/AGENTS.md`. 1. Inspect repository instructions, shape, entry points, build and proof commands, and relevant configuration. 2. Recognize managed template markers quietly. diff --git a/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md b/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md deleted file mode 100644 index 1d80ac9..0000000 --- a/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: repository-orientation -description: Explain or map an unfamiliar repository, subsystem, architecture boundary, domain territory, runtime path, or ownership area. Use when orientation is primary. ---- - -# Repository orientation - -Follow `agentic-flow/AGENTS.md` and `SETTINGS.md`. Read only relevant education guidance and shared records. - -1. Identify the intended human, business, scientific, or physical outcome. -2. Frame actor or caller, capability, governing rule, and system boundary. -3. Show a compact domain slice before file detail. -4. Trace one representative execution, data, material, or decision path. -5. Connect claims to source, tests, configuration, runtime or domain evidence, or explicit inference. -6. Identify important failure, access, deployment, legacy, or human-control boundaries when relevant. -7. Name the highest-value unknown. -8. Stop when the user can locate, explain, challenge, and safely continue. - -Ask at most one consequential trace, prediction, or explain-back. Create or update an artifact only when its persistence value is clear. - -Output a compact mental model, useful visual when appropriate, representative path, evidence, uncertainty, control boundary, and one next challenge. diff --git a/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md b/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md deleted file mode 100644 index 097cc0b..0000000 --- a/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: safe-refactor -description: Plan, perform, or teach a behavior-preserving refactor with an explicit contract, sufficient characterization evidence, a small change seam, and regression proof. Use when structural change is primary; do not expand local cleanup into an architecture campaign. ---- - -# Safe refactor - -Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md`. Read `agentic-flow/EDUCATION.md` and `learning-flow/AGENTS.md`. Load only material for the affected contract and territory. - -1. State the behavior or domain invariant that must remain stable. -2. Identify the observable contract, failure boundary, access or deployment control, and fallback that cannot be lost. -3. Inspect existing proof and add characterization only where necessary. -4. Identify the smallest safe seam. -5. Apply reviewable transformations. -6. Run the narrowest useful checks after meaningful steps. -7. Confirm the result is simpler to own, validate, recover, and explain. -8. Confirm no custom glue or AI dependency was added unnecessarily. -9. Stop when the contract is explicit, relevant checks pass, and no unproven boundary is hidden. - -Ask at most one check about the preserved contract, failure boundary, or new responsibility boundary. - -Report the contract, evidence before and after, transformation sequence, resilience preserved, simplification, and remaining risk. diff --git a/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md b/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md index 026510c..b5e1265 100644 --- a/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md +++ b/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md @@ -16,7 +16,7 @@ Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md`. Read `agentic-fl 7. Fill only high-value missing context. 8. Propose the shortest responsible route, usually one to three steps. 9. Stop at preparation unless implementation was requested. -10. Name one implementation handoff when needed: `challenge-debugging`, `analogous-feature`, or `safe-refactor`. +10. Name the implementation handoff when needed: `repository-learning` (bug, feature, or refactor branch). Do not execute several skills in the same pass. diff --git a/sample/profiles/full/learning-flow/.managed-files b/sample/profiles/full/learning-flow/.managed-files index c0a4695..8329141 100644 --- a/sample/profiles/full/learning-flow/.managed-files +++ b/sample/profiles/full/learning-flow/.managed-files @@ -4,6 +4,3 @@ .template-version README.md AGENTS.md -BOOTSTRAP.md -PLAYBOOKS.md -UNDERSTANDING_CHECKS.md diff --git a/sample/profiles/full/learning-flow/.managed-skills b/sample/profiles/full/learning-flow/.managed-skills index 6090479..45bd2cd 100644 --- a/sample/profiles/full/learning-flow/.managed-skills +++ b/sample/profiles/full/learning-flow/.managed-skills @@ -1,7 +1,4 @@ learning-bootstrap -repository-orientation -challenge-debugging -analogous-feature -safe-refactor +repository-learning change-explainer ticket-learning-path diff --git a/sample/profiles/full/learning-flow/.template-version b/sample/profiles/full/learning-flow/.template-version index 3eefcb9..9084fa2 100644 --- a/sample/profiles/full/learning-flow/.template-version +++ b/sample/profiles/full/learning-flow/.template-version @@ -1 +1 @@ -1.0.0 +1.1.0 diff --git a/sample/profiles/full/learning-flow/AGENTS.md b/sample/profiles/full/learning-flow/AGENTS.md index 5e52945..6c57138 100644 --- a/sample/profiles/full/learning-flow/AGENTS.md +++ b/sample/profiles/full/learning-flow/AGENTS.md @@ -11,14 +11,11 @@ This file governs learning-oriented repository work. Every selected learning ski | Need | Primary skill | |---|---| | compact baseline | `learning-bootstrap` | -| architecture or domain orientation | `repository-orientation` | -| bug or failing behavior | `challenge-debugging` | -| feature similar to existing behavior | `analogous-feature` | -| behavior-preserving structural change | `safe-refactor` | +| orientation, a bug, a similar feature, or a safe refactor | `repository-learning` | | non-trivial change explanation | `change-explainer` | | task context before implementation | `ticket-learning-path` | -Do not load all skills. Do not use `agentic-workflow` as a second engineering procedure. Agents without task-skill support use `PLAYBOOKS.md`. For one architecturally significant, ambiguous, or regulated change within the selected skill's work, `structured-change` may run alongside it; it does not replace the selected skill. +`repository-learning` selects one branch — Orientation, Bug, Feature, or Refactor — matching the task; see its `SKILL.md` for the branch routes. Do not load all skills. Do not use `agentic-workflow` as a second engineering procedure. For one architecturally significant, ambiguous, or regulated change within the selected skill's work, `structured-change` may run alongside it; it does not replace the selected skill. ## Shared learning flow @@ -37,6 +34,21 @@ Each pass through Locate–Reason can be one small round: one question, the evid Treat the selected territory as a system before diving into files. Prefer one representative interaction over an inventory. +## Branches + +For an agent without task-skill support, use this table directly instead of loading a `SKILL.md`: + +| Task | Learning route | +|---|---| +| Orientation | real outcome → system boundary → representative path → control and failure boundary → next territory | +| Bug | affected outcome/rule → symptom → expectation → decisive probe → mechanism → containment/fix → proof | +| Feature | actor/outcome → should it exist → invariants → valid analogue → differences → seam → proof and control | +| Refactor | behavior/invariant → evidence → failure boundary → smallest seam → transformation → proof → simpler ownership | +| Change explanation | intended outcome → governing rules → generated/human decisions → conceptual walkthrough → risks and proof | +| Ticket path | actor/outcome → ownership → build judgment → missing context → shortest route → handoff or stop | + +Use one understanding check only when consequential. Persist only verified, reusable findings. Keep AI leverage visible where useful, but retain independent evidence and fallback in proportion to risk. + ## Ownership depth When relevant, identify: @@ -65,7 +77,18 @@ Apply deeper scrutiny to laboratory, industrial, regulated, security, architectu Use at most one check by default. Skip it for fast delivery, mechanical work, or already-demonstrated understanding. Use more only for an explicit quiz or guided-learning request. -Rereading, agreement, confidence, and fluent output are not proof. See `UNDERSTANDING_CHECKS.md`. +Rereading, agreement, confidence, and fluent output are not proof. + +
+Check techniques and handling + +Useful checks: explain the mechanism in the user's own words, predict an outcome before running it, trace a path through the system, name what must stay stable under a change, compare a valid analogue against an invalid one, spot the flaw in a plausible-but-wrong explanation, state what evidence would disprove the current model, or identify the failure or fallback behavior. + +Skip a check when the task is trivial, mechanical, time-critical, or the user has already demonstrated the relevant understanding earlier in the session. + +If the response is confident but wrong, correct it plainly and continue; do not turn it into a teaching detour unless the user asks. If the user declines a check, proceed with the work. + +
## Persistence and safety diff --git a/sample/profiles/full/learning-flow/BOOTSTRAP.md b/sample/profiles/full/learning-flow/BOOTSTRAP.md deleted file mode 100644 index 7f92dc9..0000000 --- a/sample/profiles/full/learning-flow/BOOTSTRAP.md +++ /dev/null @@ -1,43 +0,0 @@ -# Compact repository learning baseline - -Use this only for a requested first map population or deliberate refresh. It creates a useful ownership map, not a repository inventory or curriculum. - -```mermaid -flowchart LR - R[Repository shape] --> S[System boundary] - S --> D[Domain slice] - D --> P[Representative path] - P --> E[Proof and control entry points] - E --> U[High-value unknowns] -``` - -## Constraints - -- Follow repository instructions, `agentic-flow/AGENTS.md`, `agentic-flow/EDUCATION.md`, and `learning-flow/AGENTS.md`. -- Do not modify application code unless explicitly combined with implementation. -- Do not pre-generate personal tracking, sessions, explainers, labs, research, or learning materials. -- Do not exhaustively reread known managed template files. - -## Procedure - -1. Inspect repository shape, entry points, existing documentation, build and test commands, and relevant configuration. -2. Recognize template markers and root integration quietly. -3. Record only consequential custom instruction exceptions. -4. Identify the real business, scientific, human, or physical system when evidence supports it. -5. Populate `MAP.md` with major boundaries, one compact domain slice, one representative path, proof entry points, and high-value unknowns. -6. Add access, deployment, failure, validation, or fallback boundaries only when relevant. -7. Record repository identity in `REPOSITORIES.md` only when useful. -8. Add `TAKEAWAYS.md` entries only when they already meet the persistence threshold. -9. Stop. - -## Completion report - -Report: - -- map entry point; -- system and domain boundary; -- representative path; -- build, run, debug, and proof entry points; -- important control or failure boundary when relevant; -- uncertain claims; -- one useful next task when obvious. diff --git a/sample/profiles/full/learning-flow/PLAYBOOKS.md b/sample/profiles/full/learning-flow/PLAYBOOKS.md deleted file mode 100644 index a069d10..0000000 --- a/sample/profiles/full/learning-flow/PLAYBOOKS.md +++ /dev/null @@ -1,18 +0,0 @@ -# Compact learning fallback - -Use this only when repository task skills are unavailable. General execution behavior remains in `agentic-flow/WORKFLOW.md`; educational behavior comes from `agentic-flow/EDUCATION.md`. - -```text -Locate → Reason → Try or Work → Verify → Explain → Transfer -``` - -| Task | Learning route | -|---|---| -| Orientation | real outcome → system boundary → representative path → control and failure boundary → next territory | -| Bug | affected outcome/rule → symptom → expectation → decisive probe → mechanism → containment/fix → proof | -| Analogous feature | actor/outcome → should it exist → invariants → valid analogue → differences → seam → proof and control | -| Refactor | behavior/invariant → evidence → failure boundary → smallest seam → transformation → proof → simpler ownership | -| Change explanation | intended outcome → governing rules → generated/human decisions → conceptual walkthrough → risks and proof | -| Ticket path | actor/outcome → ownership → build judgment → missing context → shortest route → handoff or stop | - -Use one understanding check only when consequential. Persist only verified, reusable findings. Keep AI leverage visible where useful, but retain independent evidence and fallback in proportion to risk. diff --git a/sample/profiles/full/learning-flow/README.md b/sample/profiles/full/learning-flow/README.md index 7de64ab..8d70e02 100644 --- a/sample/profiles/full/learning-flow/README.md +++ b/sample/profiles/full/learning-flow/README.md @@ -1,19 +1,14 @@ # Full learning flow -A focused repository-learning profile for deliberate onboarding and long-lived ownership. It adds narrower skills, not a second collaboration engine. +A focused repository-learning profile for deliberate onboarding and long-lived ownership. It adds deeper task skills, not a second collaboration engine. ```mermaid flowchart TB - B[Compact baseline] --> O[System and domain orientation] - O --> T{Real task} - T --> D[Debugging] - T --> F[Analogous feature] - T --> R[Safe refactor] + B[Compact baseline] --> T{Real task} + T --> L["repository-learning
(orientation, bug, feature, or refactor)"] T --> X[Change explanation] T --> P[Ticket learning path] - D --> K[Durable map or takeaway only when justified] - F --> K - R --> K + L --> K[Durable map or takeaway only when justified] X --> K ``` @@ -39,9 +34,7 @@ Select one primary learning skill. `agentic-workflow` is only for configuring or ## Understanding and assessment -Use at most one brief open checkpoint by default when a mistaken model would affect future reasoning. Credible evidence includes explanation, prediction, trace, comparison, corrected attempt, boundary identification, or transfer. - -A declined check never blocks engineering. Confidence, agreement, and polished wording are not proof. +See "Understanding checks" in `learning-flow/AGENTS.md` for the governing rule and check techniques. A declined check never blocks engineering. ## Artifact budget diff --git a/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md b/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md deleted file mode 100644 index 544a8df..0000000 --- a/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md +++ /dev/null @@ -1,49 +0,0 @@ -# Understanding checks - -Understanding checks are a small retrieval, reasoning, and transfer mechanism. They are not a compliance quiz or a confidence score. - -## Default - -Use at most one check when a mistaken model would affect future debugging, design, review, teaching, safety, or ownership. - -Prefer: - -- explain the mechanism in two to four sentences; -- predict behavior under one changed condition; -- trace one value, request, event, material, or decision through important boundaries; -- identify what must remain stable; -- compare a valid analogue with a tempting but invalid one; -- spot the flaw in a short generated explanation; -- state what evidence would disprove the current model; -- identify a failure, fallback, or human control point; -- transfer the rule to a nearby case. - -Use multiple-choice only when distinguishing plausible mechanisms is itself useful. - -## Credible assessment - -Judge the answer against the relevant model and evidence, not polish, confidence, speed, agreement, or the learner's relationship to the instructor. - -A corrected attempt can demonstrate more learning than a lucky first answer. - -For classroom, team, or onboarding settings, keep standards clear, explain the basis of assessment, and avoid humiliating or diagnostic language. - -## Skip when - -- the work is mechanical or trivial; -- the user already demonstrated the model; -- fast execution was requested; -- the answer would repeat an obvious fact; -- the same concept was already checked and later reasoning has not contradicted it. - -## Response handling - -- Correct the model directly and briefly. -- Ask one follow-up only when a central gap remains. -- Never block engineering because a check was declined. -- Record private check history only when useful for continuity. -- Do not infer broad competence, distress, identity, or diagnosis from one response. - -## Handoff - -When useful, fold a compact correction, boundary, evidence point, resilience insight, or transfer into the normal handoff. Do not add a separate recap. diff --git a/skill-evals/full-cases.yaml b/skill-evals/full-cases.yaml index 816081e..4788878 100644 --- a/skill-evals/full-cases.yaml +++ b/skill-evals/full-cases.yaml @@ -1,19 +1,19 @@ profile: full cases: - prompt: Help me understand why this endpoint sometimes returns stale data. - expected_primary_skill: challenge-debugging + expected_primary_skill: repository-learning must_include: [affected outcome or rule, symptom, decisive evidence, mechanism, regression proof] must_not: [guessed patch before narrowing, multiple primary learning skills, agentic-workflow as second task skill] - prompt: A laboratory instrument occasionally applies the wrong calibration. Diagnose it before any code change. - expected_primary_skill: challenge-debugging + expected_primary_skill: repository-learning must_include: [scientific or physical outcome, containment, decisive observation, mechanism, validation evidence, fallback or untested boundary] must_not: [guessed patch, unsafe live experiment, generic web-app assumptions] - prompt: Implement export similarly to the existing import workflow. - expected_primary_skill: analogous-feature + expected_primary_skill: repository-learning must_include: [actor and outcome, build judgment, valid analogue, invariants, intentional differences, proof and control] must_not: [blind copy, premature shared abstraction] - prompt: Clean up this service without changing its behavior. - expected_primary_skill: safe-refactor + expected_primary_skill: repository-learning must_include: [behavior or domain invariant, preserved contract, evidence, smallest seam, resilience preserved, simplification] must_not: [architecture campaign] - prompt: Review this AI-generated refactor and explain whether we can rely on it. @@ -37,7 +37,7 @@ cases: must_include: [compact system model, purpose and boundaries, relationships and flow, compact map, build and proof entry points, one representative path] must_not: [normal template status write, transient branch or commit report, exhaustive agentic inventory, prebuilt curriculum, contributor folder, generated sessions] - prompt: Help me understand this subsystem while fixing its current bug; do not run a separate onboarding pass. - expected_primary_skill: challenge-debugging + expected_primary_skill: repository-learning must_include: [task starts directly, model and evidence folded into handoff] must_not: [learning-bootstrap first, separate recap section, setup status write] - prompt: Close our repository-learning session, keep my quiz and progress history private, and preserve any takeaway useful to the whole team.