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: