From de8f07d82ec75923c6e355a4f1036f969e173cbf Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 12 Aug 2026 07:12:46 +0200 Subject: [PATCH] fix(aidd-context): make 10-learn's recommendation step consistent and enforce scope The confirm step rendered differently every run (full table, bare list, or an approval prompt with nothing shown first) and sometimes proposed learnings outside the current PR or logged a fixed bug as a decision. - assess always fills a fixed recommendation-table asset (Packet/Score/ Destination/Reconciliation, one bare value per cell) before asking approve/modify/skip, never the reverse - gather drops signals outside the source's scope and bugs fixed without an explicit request to remember them - destinations gain a `contract` case (amend an existing project contract file directly, e.g. skill-authoring.md) and reconciliation gains `retracts` (remove, no replacement), each with a real apply rule - write-report asset gives 04-write a fixed add/modify/remove report, matching the emoji convention already used in 01-plan - dedup pass across router/actions/references: removed restated rules, merged near-duplicate destination rows, closed a gap where the assess step never emitted a source scope for gather to filter against Fixes #561 Co-Authored-By: Claude Sonnet 5 --- plugins/aidd-context/CATALOG.md | 2 ++ plugins/aidd-context/skills/10-learn/SKILL.md | 8 +++-- .../skills/10-learn/actions/01-source.md | 4 +-- .../skills/10-learn/actions/03-assess.md | 10 +++++-- .../skills/10-learn/actions/04-write.md | 10 ++++--- .../skills/10-learn/actions/05-sync.md | 2 +- .../skills/10-learn/assets/learning-packet.md | 8 ++--- .../10-learn/assets/recommendation-table.md | 5 ++++ .../skills/10-learn/assets/write-report.md | 7 +++++ .../skills/10-learn/references/assessment.md | 3 +- .../10-learn/references/destinations.md | 15 +++++++--- .../10-learn/references/gather-protocol.md | 29 +++++++++---------- .../10-learn/references/review-protocol.md | 4 +-- .../skills/10-learn/references/sources.md | 3 +- 14 files changed, 70 insertions(+), 40 deletions(-) create mode 100644 plugins/aidd-context/skills/10-learn/assets/recommendation-table.md create mode 100644 plugins/aidd-context/skills/10-learn/assets/write-report.md diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index f59078fd9..8e17421e5 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -180,6 +180,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [05-sync.md](skills/10-learn/actions/05-sync.md) | - | | `assets` | [adr-template.md](skills/10-learn/assets/adr-template.md) | - | | `assets` | [learning-packet.md](skills/10-learn/assets/learning-packet.md) | - | +| `assets` | [recommendation-table.md](skills/10-learn/assets/recommendation-table.md) | - | +| `assets` | [write-report.md](skills/10-learn/assets/write-report.md) | - | | `references` | [assessment.md](skills/10-learn/references/assessment.md) | - | | `references` | [destinations.md](skills/10-learn/references/destinations.md) | - | | `references` | [gather-protocol.md](skills/10-learn/references/gather-protocol.md) | - | diff --git a/plugins/aidd-context/skills/10-learn/SKILL.md b/plugins/aidd-context/skills/10-learn/SKILL.md index d80b29b5f..8e1c5e63c 100644 --- a/plugins/aidd-context/skills/10-learn/SKILL.md +++ b/plugins/aidd-context/skills/10-learn/SKILL.md @@ -8,8 +8,12 @@ argument-hint: conversation | file | diff | review ```mermaid flowchart LR source --> gather --> assess --> write + source -->|"missing, empty, or ambiguous"| sourceStop([stop]) + gather -->|"no candidates"| gatherEnd([end]) + assess -->|"all covered"| assessEnd([end]) write -->|"memory or ADR"| sync write -->|"rule or skill"| handoff([handoff]) + sync -->|"failure"| syncStop([stop]) ``` ## Actions @@ -20,7 +24,7 @@ Run the flow above. Read only the next action file. | ------ | ---- | | source | identify and challenge the origin | | gather | read the origin and extract candidates | -| assess | score, reconcile, and confirm | +| assess | score, reconcile, show, and confirm | | write | write or hand off approved lessons | | sync | refresh memory references | @@ -28,4 +32,4 @@ Run the flow above. Read only the next action file. - Write only the user-approved plan. - Preserve user edits and touch affected files only. -- Write project files only, never personal or global memory, never scaffold `aidd_docs/memory/` yourself. +- Write project files only, never personal or global memory. diff --git a/plugins/aidd-context/skills/10-learn/actions/01-source.md b/plugins/aidd-context/skills/10-learn/actions/01-source.md index 941ef431d..4ad8d2934 100644 --- a/plugins/aidd-context/skills/10-learn/actions/01-source.md +++ b/plugins/aidd-context/skills/10-learn/actions/01-source.md @@ -16,11 +16,11 @@ One or more source descriptions that name where to look and how narrowly to read 2. **Select.** Select the smallest readable source set that fits the current context. 3. **Ask.** Ask only when the source choice would change what gets learned. 4. **Stop.** Stop on a missing, empty, or ambiguous source. -5. **Emit.** Emit the selected source descriptions. +5. **Emit.** Emit each source's kind, label, and scope. ## Test | Case | Pass | | --- | --- | -| A source is readable | one or more source descriptions are emitted | +| A source is readable | one or more sources are emitted, each with kind, label, and scope | | A source cannot be read | the run stops and names it | diff --git a/plugins/aidd-context/skills/10-learn/actions/03-assess.md b/plugins/aidd-context/skills/10-learn/actions/03-assess.md index aba6ea350..e908a57fc 100644 --- a/plugins/aidd-context/skills/10-learn/actions/03-assess.md +++ b/plugins/aidd-context/skills/10-learn/actions/03-assess.md @@ -12,9 +12,10 @@ A learning plan approved by the user and ready to write. ## Process -1. **Frame.** Apply [assessment](../references/assessment.md), then use [destinations](../references/destinations.md) to propose where each candidate should land. -2. **Score.** Score each candidate and reconcile existing coverage. -3. **Confirm.** Show the scored recommendation and ask which packets to approve, edit, redirect, or skip. +1. **Score.** Apply [assessment](../references/assessment.md) and [destinations](../references/destinations.md): reason internally to a 0-10 score, reconcile existing coverage, and propose where it lands. +2. **Show.** State the source in one line, then fill and show the [recommendation table](../assets/recommendation-table.md). +3. **Confirm.** Ask, per packet: approve, modify, or skip. + - When every packet is covered, skip the question. 4. **Fill.** Fill [learning packet](../assets/learning-packet.md) for approved items only. ## Test @@ -23,3 +24,6 @@ A learning plan approved by the user and ready to write. | --- | --- | | A packet is approved | it carries score, approved destination, reconciliation, and user approval | | An item is skipped or already covered | it is not written | +| The confirm step runs | only the source line and the table appear before it | +| The confirm question is asked | it names approve, modify, and skip | +| Every candidate is covered | the run ends, nothing is asked | diff --git a/plugins/aidd-context/skills/10-learn/actions/04-write.md b/plugins/aidd-context/skills/10-learn/actions/04-write.md index 8d629aad9..075f0913f 100644 --- a/plugins/aidd-context/skills/10-learn/actions/04-write.md +++ b/plugins/aidd-context/skills/10-learn/actions/04-write.md @@ -12,11 +12,12 @@ The created or updated files, and a summary table. ## Process -1. **Start.** Start from the approved learning packet. -2. **Route.** Apply only the destination path in [destinations](../references/destinations.md). -3. **Fill.** Load the destination asset when one is required, fill it from the packet, and strip its guidance comment. +1. **Start.** Start from each approved learning packet. +2. **Route.** Apply the destination and reconciliation rules in [destinations](../references/destinations.md). +3. **Fill.** Load the destination asset when one is required and follow its instructions. + - For a retraction, remove the entry instead of filling one. 4. **Review.** Apply [review protocol](../references/review-protocol.md) to every touched file or handoff. -5. **Report.** Report packet, destination, action, file or handoff, and review verdict. +5. **Report.** Fill [write report](../assets/write-report.md) grouped by destination. ## Test @@ -25,3 +26,4 @@ The created or updated files, and a summary table. | A lesson is approved | it appears in the table, at the destination the user chose | | A packet has no user approval | it is neither written nor handed off | | The report is delivered | it carries a review verdict for every touched file and handoff | +| A candidate retracts existing content | the entry is removed, not left in place with a note | diff --git a/plugins/aidd-context/skills/10-learn/actions/05-sync.md b/plugins/aidd-context/skills/10-learn/actions/05-sync.md index 393c38666..441baa33a 100644 --- a/plugins/aidd-context/skills/10-learn/actions/05-sync.md +++ b/plugins/aidd-context/skills/10-learn/actions/05-sync.md @@ -4,7 +4,7 @@ Refresh context references after memory or ADR writes. ## Input -The write summary, confirming at least one memory or ADR file changed. Skip this action when write only handed off rules or skills. +The write summary, confirming at least one memory or ADR file changed. ## Output diff --git a/plugins/aidd-context/skills/10-learn/assets/learning-packet.md b/plugins/aidd-context/skills/10-learn/assets/learning-packet.md index 7615f4b84..1d76fe0af 100644 --- a/plugins/aidd-context/skills/10-learn/assets/learning-packet.md +++ b/plugins/aidd-context/skills/10-learn/assets/learning-packet.md @@ -6,8 +6,8 @@ - Source: - Evidence: - Score: <0-10 + reason> -- Destination: -- Reconciliation: -- User approval: -- Scope: +- Destination: +- Reconciliation: +- User approval: +- Applies to: - Request: diff --git a/plugins/aidd-context/skills/10-learn/assets/recommendation-table.md b/plugins/aidd-context/skills/10-learn/assets/recommendation-table.md new file mode 100644 index 000000000..0e32dbe95 --- /dev/null +++ b/plugins/aidd-context/skills/10-learn/assets/recommendation-table.md @@ -0,0 +1,5 @@ + + +| Packet | Score | Destination | Reconciliation | +| --- | --- | --- | --- | +| | <0-10> | <memory \| ADR \| contract: \<file\> \| rule \| skill> | <✅ new \| covered \| ✏️ updates \| ✏️ supersedes \| ❌ retracts> | diff --git a/plugins/aidd-context/skills/10-learn/assets/write-report.md b/plugins/aidd-context/skills/10-learn/assets/write-report.md new file mode 100644 index 000000000..b867a42aa --- /dev/null +++ b/plugins/aidd-context/skills/10-learn/assets/write-report.md @@ -0,0 +1,7 @@ +<!-- Group rows by destination, one row per touched file or handoff, then strip this comment. --> + +### <memory | ADR | contract | rule | skill> + +| Action | File | Lesson | Review | +| --- | --- | --- | --- | +| <✅ add \| ✏️ modify \| ❌ remove> | <path, "new" when created> | <the lesson written> | <verdict> | diff --git a/plugins/aidd-context/skills/10-learn/references/assessment.md b/plugins/aidd-context/skills/10-learn/references/assessment.md index 4dd0edcab..15e290b35 100644 --- a/plugins/aidd-context/skills/10-learn/references/assessment.md +++ b/plugins/aidd-context/skills/10-learn/references/assessment.md @@ -21,4 +21,5 @@ Reconcile before approval: - `new`: no equivalent content exists. - `covered`: existing content already carries it. - `updates`: refine an existing memory, rule, ADR, or skill. -- `supersedes`: reverses an earlier decision or rule; require an explicit link. +- `supersedes`: reverses an earlier decision or rule. +- `retracts`: existing content no longer holds and nothing replaces it. diff --git a/plugins/aidd-context/skills/10-learn/references/destinations.md b/plugins/aidd-context/skills/10-learn/references/destinations.md index cfc0b610e..cf7f8a5b5 100644 --- a/plugins/aidd-context/skills/10-learn/references/destinations.md +++ b/plugins/aidd-context/skills/10-learn/references/destinations.md @@ -6,15 +6,22 @@ Every destination starts from the approved learning packet. | ----------- | -------- | ----- | | memory | durable project fact, convention, or gotcha | write the packet into the matching memory entry | | ADR | explicit choice with context and consequences | write the packet to `aidd_docs/memory/internal/decisions/<slug>.md` through [ADR template](../assets/adr-template.md) | -| rule | enforceable coding or agent behavior | send the packet to rule-generate | +| contract | enforceable behavior already owned by an existing project contract file | write the packet by amending that file | +| rule | enforceable coding or agent behavior with no existing owner | send the packet to rule-generate | | skill | reusable workflow worth a dedicated skill | send the packet to skill-generate | +Reconciliation: + +| Value | Apply | +| --- | --- | +| updates | replace the existing entry; do not add contradictions | +| supersedes | replace the entry; link both decision records for an ADR | +| retracts | remove the entry; delete the file only when nothing remains | + Rules: - If the project memory bank is missing, say what is missing and ask before handing off to project-memory. - If the destination structure is unclear, ask. Do not invent a new taxonomy. -- Replace superseded entries. Do not add contradictions. -- For ADR supersession, link both decision records. - Prefer the narrowest destination that can own the lesson. - The user may choose another destination after seeing the recommendation. -- Learn writes memory and ADRs. Learn hands off rules and skills. +- Write memory, ADRs, and contract amendments directly. Hand off rules and skills. diff --git a/plugins/aidd-context/skills/10-learn/references/gather-protocol.md b/plugins/aidd-context/skills/10-learn/references/gather-protocol.md index eba80bc02..8ad631959 100644 --- a/plugins/aidd-context/skills/10-learn/references/gather-protocol.md +++ b/plugins/aidd-context/skills/10-learn/references/gather-protocol.md @@ -2,21 +2,20 @@ Extract only durable project learning. -Keep: - -- Decision, tradeoff, or consequence. -- Convention or recurring project rule. -- Pitfall, failed path, or costly pivot. -- Reusable workflow worth documenting or automating. -- Missing context that should prevent the same confusion later. - -Drop: - -- Personal preferences. -- AI behavior preferences. -- Routine implementation details. -- One-off facts with no reuse. -- Items already obviously covered by the source itself. +| Signal | Verdict | +| --- | --- | +| Decision, tradeoff, or consequence | Keep | +| Convention or recurring project rule | Keep | +| Pitfall, failed path, or costly pivot | Keep | +| Reusable workflow worth documenting or automating | Keep | +| Missing context that should prevent the same confusion later | Keep | +| Personal preference | Drop | +| AI behavior preference | Drop | +| Routine implementation detail | Drop | +| One-off fact with no reuse | Drop | +| Item already obviously covered by the source itself | Drop | +| Signal outside the selected source's scope, even when noticed while reading | Drop | +| Bug already fixed as part of the current change, unless the user explicitly asked to remember it as a decision | Drop | For each candidate, include: diff --git a/plugins/aidd-context/skills/10-learn/references/review-protocol.md b/plugins/aidd-context/skills/10-learn/references/review-protocol.md index f5ee71c22..f8b5ef286 100644 --- a/plugins/aidd-context/skills/10-learn/references/review-protocol.md +++ b/plugins/aidd-context/skills/10-learn/references/review-protocol.md @@ -7,7 +7,7 @@ Check: - The approved packet is represented. - No duplicate or contradictory entry was added. - Superseded ADRs or rules point to the newer decision. +- A retracted entry is gone, not just marked. +- A contract amendment lands in the file the packet names. - Memory and ADR references are synced when those destinations changed. - Rule and skill handoffs carry the approved packet and name the target generator. - -Do not expand scope into unrelated project cleanup. diff --git a/plugins/aidd-context/skills/10-learn/references/sources.md b/plugins/aidd-context/skills/10-learn/references/sources.md index 3d4e7f9e3..7fa839b19 100644 --- a/plugins/aidd-context/skills/10-learn/references/sources.md +++ b/plugins/aidd-context/skills/10-learn/references/sources.md @@ -18,9 +18,8 @@ Kind meaning: Selection: - Explicit hint narrows the source kind. -- No hint defaults to the current conversation, same as before this skill could take an explicit pointer. +- No hint defaults to the current conversation. - Multiple specs are allowed when one source cannot explain the learning alone. -- Ask before continuing when several source sets are plausible. Limits: