refactor(aidd-context): rework 10-learn around scoring and explicit confirm

plugins/aidd-context/CATALOG.md

@@ -169,15 +169,15 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 #### `skills/10-learn`
 
-| Group | File | Description | Argument Hint |
-|-------|------|---|---|
-| `actions` | [01-scope.md](skills/10-learn/actions/01-scope.md) | - | - |
-| `actions` | [02-write.md](skills/10-learn/actions/02-write.md) | - | - |
-| `actions` | [03-sync.md](skills/10-learn/actions/03-sync.md) | - | - |
-| `assets` | [adr-template.md](skills/10-learn/assets/adr-template.md) | `Architecture Decision Record template` | - |
-| `assets` | [decision-template.md](skills/10-learn/assets/decision-template.md) | `Individual decision record template` | `<title>` |
-| `-` | [README.md](skills/10-learn/README.md) | - | - |
-| `-` | [SKILL.md](skills/10-learn/SKILL.md) | `Capture and store project-level learnings, conventions, and decisions surfaced during work into memory, decisions, or rules. Use proactively when the user states a durable project rule or convention ("for next", "always do X", "from now on", "going forward", "rule:", "convention:"), records a technical decision and its rationale, deprecates something, or notes an insight that should outlive the current task. Do NOT use for personal or AI-preference reminders (those belong to user memory), routine code edits, minor fixes, or anything already captured.` | - |
+| Group | File | Description |
+|-------|------|---|
+| `actions` | [01-gather.md](skills/10-learn/actions/01-gather.md) | - |
+| `actions` | [02-assess.md](skills/10-learn/actions/02-assess.md) | - |
+| `actions` | [03-write.md](skills/10-learn/actions/03-write.md) | - |
+| `actions` | [04-sync.md](skills/10-learn/actions/04-sync.md) | - |
+| `assets` | [decision-template.md](skills/10-learn/assets/decision-template.md) | - |
+| `-` | [README.md](skills/10-learn/README.md) | - |
+| `-` | [SKILL.md](skills/10-learn/SKILL.md) | `Capture durable project learnings from the conversation or the project's git history and route them to memory, a decision record, a rule, or a new skill. Use when the user asks to capture, record, or remember a decision, a convention, or a lesson, or to distill what recent work taught. Scores each candidate and confirms before writing. Not for personal or AI preferences, routine edits, or anything already captured.` |
 
 #### `skills/11-discovery`
 

plugins/aidd-context/skills/10-learn/README.md

@@ -1,60 +1,43 @@
-← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md)
+← [framework](../../../../README.md) / [aidd-context](../../README.md)
 
-# 05 - Learn
+# 10 - Learn
 
-Captures durable project-level learnings, conventions, and decisions
-surfaced during work and stores them as memory entries, decision records,
-or rules. Then refreshes the `<aidd_project_memory>` block in installed AI
-context files so the new knowledge is in scope on the next turn.
+Distills what a piece of work taught into the project's lasting context. It picks a source, scores each candidate learning, asks the user what to do with each one, writes only the approved lessons, and refreshes the memory block so the next session starts from them.
 
 ## When to use
 
-- The user states a durable rule or convention ("for next", "always do X",
-  "from now on", "going forward", "rule:", "convention:").
-- A technical decision is made and worth recording with its rationale.
-- Something is deprecated, or an insight should outlive the current task.
+- The user states a lasting rule or convention ("from now on", "always", "going forward").
+- A decision is made and worth recording with its rationale.
+- Something is deprecated, or a piece of work is worth distilling before moving on.
 
-## When NOT to use
+## When not to use
 
-- For personal or AI-preference reminders (those belong in user memory,
-  not project memory).
-- For routine code edits, minor fixes, or anything already captured.
-- To initialize the memory bank itself → use `02-project-memory`.
+- For personal or AI-preference reminders. Those belong in user memory, not the project.
+- For routine edits, minor fixes, or anything already captured.
+- To stand up the memory bank itself. Use `aidd-context:02-project-memory`.
 
-## How to invoke
+## Requires
 
-```
-Use skill aidd-context:10-learn
-```
+An existing memory bank (`aidd_docs/memory/`). If it is missing, run `aidd-context:02-project-memory` first.
 
-The skill walks 3 atomic actions:
+## Flow
 
-1. `scope` - worth-learning check, auto-analyze, categorize, and get
-   explicit user approval. Exits cleanly here when nothing is
-   learning-worthy (gates 02 and 03 out).
-2. `write` - create or update files for each approved item (memory entry,
-   decision record, or rule).
-3. `sync` - refresh the `<aidd_project_memory>` block in installed AI
-   context files so the new content is loaded next turn.
+Four actions, in order:
 
-## Outputs
+1. `gather`: pick a source (the conversation, the git history, or one the user names), collect candidates, drop the noise.
+2. `assess`: score each candidate from 0 to 10 with a reason, propose a destination, and ask the user what to do with each.
+3. `write`: write the lessons the user approved to their destinations.
+4. `sync`: refresh the memory block in every context file.
 
-- New or updated files under `aidd_docs/memory/`, `aidd_docs/decisions/`,
-  or the rules directory, depending on the categorization in action 01.
-- Refreshed `<aidd_project_memory>` block across every installed AI
-  context file.
-- A short summary table of what was learned and where it went.
+## Destinations
 
-## Prerequisites
+- **Memory**: a fact or convention, into the matching memory file.
+- **Decision**: a choice with a rationale, a record in `aidd_docs/memory/internal/decisions/` from `assets/decision-template.md`.
+- **Rule**: a convention to enforce, handed to `aidd-context:05-rule-generate`.
+- **Skill**: a reusable workflow, handed to `aidd-context:04-skill-generate`.
 
-- Project initialized with the AIDD context layer (run `02-project-memory`
-  first if `aidd_docs/memory/` is missing).
-- A conversation signal worth capturing - the skill exits cleanly when
-  there isn't one.
+The score is the brake (bar 6 of 10), and the user decides every item before anything is written.
 
-## Technical details
+## Details
 
-See [`SKILL.md`](SKILL.md) for the action contract,
-[`actions/`](actions/) for each step, and the templates in
-`assets/decision-template.md` and `assets/adr-template.md` for decision
-records.
+See [`SKILL.md`](SKILL.md) and [`actions/`](actions/).

plugins/aidd-context/skills/10-learn/SKILL.md

@@ -1,32 +1,38 @@
 ---
 name: 10-learn
-description: Capture and store project-level learnings, conventions, and decisions surfaced during work into memory, decisions, or rules. Use proactively when the user states a durable project rule or convention ("for next", "always do X", "from now on", "going forward", "rule:", "convention:"), records a technical decision and its rationale, deprecates something, or notes an insight that should outlive the current task. Do NOT use for personal or AI-preference reminders (those belong to user memory), routine code edits, minor fixes, or anything already captured.
+description: Capture durable project learnings from the conversation or the project's git history and route them to memory, a decision record, a rule, or a new skill. Use when the user asks to capture, record, or remember a decision, a convention, or a lesson, or to distill what recent work taught. Scores each candidate and confirms before writing. Not for personal or AI preferences, routine edits, or anything already captured.
 ---
 
-# Skill: learn
+# Learn
 
-Updates memory bank, decisions, and rules to keep project context accurate after implementation.
+Turns what a piece of work taught into the project's lasting context. It reads a source, scores each lesson, asks the user what to do with each, and writes only what the user approves.
 
-## Rules
+## Actions
 
-- Less is more. Documentation stays concise and to the point.
-- Avoid putting too much information.
-- Focus on important changes or non-alignments with existing docs.
-- Memory must ALWAYS be up-to-date.
+| #   | Action   | Role                                                   | Input             |
+| --- | -------- | ------------------------------------------------------ | ----------------- |
+| 01  | `gather` | Pick a source and collect candidate lessons             | the trigger       |
+| 02  | `assess` | Score each lesson, propose a destination, ask the user  | the candidates    |
+| 03  | `write`  | Write the approved lessons to their destinations        | the approved plan |
+| 04  | `sync`   | Refresh the memory block in every context file          | the written files |
 
-## Available actions
+Order: `01 → 02 → 03 → 04`. Run each action's `## Test` before the next. When nothing is worth learning, `01` exits and the rest is skipped.
 
-| #   | Action     | Role                                                                       | Input                  |
-| --- | ---------- | -------------------------------------------------------------------------- | ---------------------- |
-| 01  | `scope`    | Worth-learning check, auto-analyze, categorize, user approval              | conversation signal    |
-| 02  | `write`    | Create or update files for each approved item                              | approved plan from 01  |
-| 03  | `sync`     | Refresh `<aidd_project_memory>` block in installed AI context files        | summary table from 02  |
+## Destinations
 
-## Default flow
+- **Memory.** A fact or convention. Update the matching memory file.
+- **Decision.** A choice with a rationale. A record in `aidd_docs/memory/internal/decisions/`, written from the decision template.
+- **Rule.** A convention to enforce. Handed to the rule generator, never written here.
+- **Skill.** A reusable workflow. Handed to the skill generator, never written here.
 
-`01 → 02 → 03`. Action 01 exits cleanly when nothing is learning-worthy (Phase 1 gate); 02 and 03 are skipped in that case.
+## Transversal rules
+
+- Ask before you write. For every lesson, show its score and proposed destination, and let the user keep it, move it, or skip it. Write nothing anywhere until the user answers.
+- Default to not capturing. The score is the brake. Recommend the bar at 6 of 10.
+- Learn needs an existing memory bank. If `aidd_docs/memory/` is absent, route to the project-memory skill, do not scaffold here.
+- Capture the user's project, never AIDD's own scaffold.
+- Touch only what a lesson affects. Preserve the user's edits. Write files, never display their content.
 
 ## Assets
 
-- `@assets/decision-template.md` - individual decision record template
-- `@assets/adr-template.md` - ADR log template
+- `assets/decision-template.md`: the decision record format.

plugins/aidd-context/skills/10-learn/actions/01-gather.md

@@ -0,0 +1,26 @@
+# 01 - Gather
+
+Pick where the learning comes from, collect the raw candidates, and drop anything not worth a second look.
+
+## Input
+
+The trigger: the user invoked the skill, or a conversation signal auto-routed to it.
+
+## Output
+
+A list of raw candidate learnings, each tagged with the source it came from. An empty list when nothing surfaced, which ends the skill.
+
+## Process
+
+1. **Pick the source.** Offer three and let the user choose, or take the one the user named:
+   - the current conversation, for recent decisions, pivots, and stated conventions,
+   - the project's git history, for recent commits or the current branch's diff against the main line,
+   - a source the user points at, like a file, a change set, or a range.
+
+   Block on the choice when it is ambiguous. Default to the conversation when the user gives no steer. If the git source yields nothing (not a repository, on the main line with no branch, or an empty diff), say so and fall back to the conversation or ask the user.
+2. **Collect.** From the chosen source, pull the raw signals: a stated rule or convention, a decision and its reason, a deprecation, a pivot that cost time, a pattern worth reusing, a pitfall worth avoiding. Read git changes for what changed and why, not line by line.
+3. **Drop noise.** Remove anything personal, an AI preference, a routine edit, or already captured in memory, a rule, or a decision. These never reach scoring.
+
+## Test
+
+- The action emits a candidate list where every item names its source, or it prints a one-line skip and ends when nothing survives the noise filter.

plugins/aidd-context/skills/10-learn/actions/02-assess.md

@@ -0,0 +1,21 @@
+# 02 - Assess
+
+Score each candidate, propose where it goes, and let the user decide every one.
+
+## Input
+
+The candidate lessons from action 01, each with its source.
+
+## Output
+
+A plan the user has approved: the lessons to keep, each with its destination.
+
+## Process
+
+1. **Score.** Give each candidate a relevance score from 0 to 10 with a one-line reason. Weigh how durable it is, how far it generalizes beyond this task, and whether it extends or contradicts existing context.
+2. **Propose and reconcile.** For each candidate, name the destination it fits (Memory, Decision, Rule, or Skill, see the skill's Destinations). Then read that destination's current content and classify the candidate against it: new, already covered, or a change to what is there. A reworded repeat of something already captured is already covered, not a new lesson, even when the existing wording differs. A candidate that reverses an existing entry supersedes it.
+3. **Ask.** Show the candidates sorted by score, each with its score, reason, destination, and how it reconciles (new, already covered, or supersedes). Recommend the bar at 6 of 10 and recommend skipping the already-covered ones. For every candidate, let the user keep it, move it to another destination, or skip it. Write nothing anywhere until the user has decided. Block on the answer.
+
+## Test
+
+- Every candidate carries a score, a reason, a proposed destination, and a reconcile classification against that destination's current content, and the action writes nothing before the user has decided each one.