From 05a40ceb7ff0707bbb64d84732342665ed00f742 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 16 Jun 2026 21:34:29 +0200 Subject: [PATCH] refactor(aidd-context): rework 10-learn around scoring and explicit confirm Rebuild the learn skill so it reads a source, scores each lesson, asks the user what to do with each, and writes only what they approve. - 4 actions (gather, assess, write, sync) with the Input/Output/Process/Test anatomy; the SKILL.md router gains a plain Destinations block. - assess scores each candidate 0-10, proposes a destination, and reconciles it against the destination's current content (new, already covered, or supersedes) so a reworded repeat is not re-added and a reversal replaces the stale entry. - four destinations: Memory (fold into the matching file), Decision (a record in aidd_docs/memory/internal/decisions/ from the template), Rule and Skill (handed to their generators, never authored here). - description advertises only the directive triggers it reliably fires on. - drop the old DEC-XXX / ADR.md ceremony and the command-frontmatter templates for one clean decision-record template. Validated end to end via headless claude -p: routes, the score brake, contradiction-supersede, multi-item, exact-duplicate dedup, and a French directive (the description matches intent across languages). Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-context/CATALOG.md | 18 ++--- .../aidd-context/skills/10-learn/README.md | 69 +++++++------------ plugins/aidd-context/skills/10-learn/SKILL.md | 42 ++++++----- .../skills/10-learn/actions/01-gather.md | 26 +++++++ .../skills/10-learn/actions/01-scope.md | 56 --------------- .../skills/10-learn/actions/02-assess.md | 21 ++++++ .../skills/10-learn/actions/02-write.md | 38 ---------- .../skills/10-learn/actions/03-sync.md | 24 ------- .../skills/10-learn/actions/03-write.md | 24 +++++++ .../skills/10-learn/actions/04-sync.md | 21 ++++++ .../skills/10-learn/assets/adr-template.md | 24 ------- .../10-learn/assets/decision-template.md | 41 +++-------- 12 files changed, 159 insertions(+), 245 deletions(-) create mode 100644 plugins/aidd-context/skills/10-learn/actions/01-gather.md delete mode 100644 plugins/aidd-context/skills/10-learn/actions/01-scope.md create mode 100644 plugins/aidd-context/skills/10-learn/actions/02-assess.md delete mode 100644 plugins/aidd-context/skills/10-learn/actions/02-write.md delete mode 100644 plugins/aidd-context/skills/10-learn/actions/03-sync.md create mode 100644 plugins/aidd-context/skills/10-learn/actions/03-write.md create mode 100644 plugins/aidd-context/skills/10-learn/actions/04-sync.md delete mode 100644 plugins/aidd-context/skills/10-learn/assets/adr-template.md diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 69797cf7..fed9a937 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/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` | `` | -| `-` | [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` diff --git a/plugins/aidd-context/skills/10-learn/README.md b/plugins/aidd-context/skills/10-learn/README.md index c6fcaf65..d091b63c 100644 --- a/plugins/aidd-context/skills/10-learn/README.md +++ b/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/). diff --git a/plugins/aidd-context/skills/10-learn/SKILL.md b/plugins/aidd-context/skills/10-learn/SKILL.md index c6726873..2abbab67 100644 --- a/plugins/aidd-context/skills/10-learn/SKILL.md +++ b/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. diff --git a/plugins/aidd-context/skills/10-learn/actions/01-gather.md b/plugins/aidd-context/skills/10-learn/actions/01-gather.md new file mode 100644 index 00000000..35253a05 --- /dev/null +++ b/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. diff --git a/plugins/aidd-context/skills/10-learn/actions/01-scope.md b/plugins/aidd-context/skills/10-learn/actions/01-scope.md deleted file mode 100644 index 56cdbe62..00000000 --- a/plugins/aidd-context/skills/10-learn/actions/01-scope.md +++ /dev/null @@ -1,56 +0,0 @@ -# 01 - Scope - -Decide if the surfaced information is learning-worthy, analyze it, propose destinations, and wait for user approval. Skip cleanly when nothing is learning-worthy. - -## Inputs - -- Conversation context covering recently implemented work, decisions, deprecations, or insights. -- Existing project memory (`aidd_docs/memory/`), decisions (`aidd_docs/internal/decisions/`), and rules. - -## Outputs - -One of two outcomes: - -- **Skipped**: a one-line `Nothing learning-worthy detected, skipping.` and the skill exits. -- **Approved plan**: a numbered list of items, each with a category and a target destination, confirmed by the user. - -```text -1. <item> → Memory → aidd_docs/memory/<file>.md -2. <item> → Decision → aidd_docs/internal/decisions/<id>-<title>.md -3. <item> → Rule → <project rules location>/<file>.md -``` - -## Process - -1. **Worth-learning check (auto-trigger only).** If the user invoked the skill → skip this check and continue to step 2. If the skill auto-routed from conversation signal, score: - - Contradicts or extends existing context (memory, rules, decisions)? - - Generalizable beyond the current task? - - Explicit decision, convention, deprecation, or "next time we should" insight (not an implicit style choice)? - - If at least 2 of 3 are `yes` → continue. Otherwise → print the skip line and exit cleanly. - -2. **Gather context.** List `aidd_docs/` (`ls -1tr aidd_docs/`). Pin the files that may need updates. - -3. **Auto-analyze.** Answer 5 questions about the recent work: - - What worked well? (effective patterns, successful approaches) - - What did not work or required multiple attempts? (corrections, pivots) - - What decisions were made and why? (technical choices, rationale) - - What patterns should be reused? (reusable solutions, conventions) - - What should be avoided next time? (anti-patterns, pitfalls) - -4. **Categorize.** For each candidate item, map to its destination using: - - | Category | Destination | Examples | - | ---------------------- | ------------------------------- | --------------------------------------- | - | **Decisions** | `aidd_docs/internal/decisions/` | Tech decisions | - | **Memory** (mandatory) | `aidd_docs/memory/` | Project context, stack updates | - | **Rules** | project rules location | Coding conventions, patterns to enforce | - | **Skills** | project skills location | Reusable prompts, workflows | - | **Templates** | plugin assets directories | Skill-specific templates | - -5. **Confirm with user.** Show the numbered plan and ask: `Here's the plan. Which items do you confirm?` Wait for explicit approval before passing to action 02. - -## Test - -- For a non-learning signal: action prints the skip line and writes nothing. -- For a learning-worthy signal: action emits a numbered plan where every approved item has a non-empty `category` and a concrete `destination` path, and the user has explicitly confirmed before action 02 starts. diff --git a/plugins/aidd-context/skills/10-learn/actions/02-assess.md b/plugins/aidd-context/skills/10-learn/actions/02-assess.md new file mode 100644 index 00000000..9def3fc0 --- /dev/null +++ b/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. diff --git a/plugins/aidd-context/skills/10-learn/actions/02-write.md b/plugins/aidd-context/skills/10-learn/actions/02-write.md deleted file mode 100644 index 6e23238c..00000000 --- a/plugins/aidd-context/skills/10-learn/actions/02-write.md +++ /dev/null @@ -1,38 +0,0 @@ -# 02 - Write - -Create or update files for each approved item from action 01, using the matching template when applicable. - -## Inputs - -- Approved plan emitted by action 01 (numbered items with `category` + `destination`). - -## Outputs - -``` -One or more files created or updated across: - aidd_docs/memory/<file>.md - aidd_docs/internal/decisions/<id>-<title>.md - ADR.md - <project rules location>/<file>.md -``` - -A summary table: `item | destination | action taken (created | updated)`. - -## Process - -1. **For each approved item**, apply by category: - - **Decision** → create `aidd_docs/internal/decisions/XXX-<title>.md` from `@../assets/decision-template.md`; assign the next `DEC-XXX` id. - - **ADR row** → update `ADR.md` using `@../assets/adr-template.md` shape (one new row referencing the decision file). - - **Memory** → update the matching `aidd_docs/memory/<file>.md`. Append or revise the relevant section; preserve user customizations. - - **Rule** → create or update the file under the project rules location. - - **Skill / Template** → create or update under the project skills or assets location. - -2. **Apply content rules** (from the skill-level rules in `SKILL.md`): - - Concise, focused, no filler. - - Reference only the section that the new info affects; do not rewrite entire files. - -3. **Print the summary table** listing every item, its destination, and whether it was `created` or `updated`. - -## Test - -Every item from the approved plan has a corresponding entry in the summary table with `created` or `updated`; for `created` entries, the destination file exists on disk; for `updated` entries, the destination file contains the new content. diff --git a/plugins/aidd-context/skills/10-learn/actions/03-sync.md b/plugins/aidd-context/skills/10-learn/actions/03-sync.md deleted file mode 100644 index bf6fa929..00000000 --- a/plugins/aidd-context/skills/10-learn/actions/03-sync.md +++ /dev/null @@ -1,24 +0,0 @@ -# 03 - Sync - -Refresh the `<aidd_project_memory>` block in all installed AI context files so the new or updated memory files are referenced. - -## Inputs - -- Summary table from action 02 (used to confirm at least one memory file changed). - -## Outputs - -``` -The <aidd_project_memory> block in every installed context file now references the current contents of aidd_docs/memory/. -``` - -## Process - -1. Execute the `update_memory.js` script located at `hooks/update_memory.js` under the plugin install root to sync memory references in context files. -2. If the script exits with a non-zero code, print the error output and stop. Instruct the user to verify `aidd_docs/memory/` contains at least one `.md` file and that `node` is available. -3. Read the script output. Count the number of AI context files updated and the number of memory references injected into each block. -4. Print a summary line: `Updated <N> AI context files (<comma-separated paths>). Each <aidd_project_memory> block now references <M> memory files from aidd_docs/memory/.` - -## Test - -For every installed AI context file, the `<aidd_project_memory>` block contains a reference line per `.md` file currently in `aidd_docs/memory/`; the summary line names the actual files updated (not a hardcoded count). diff --git a/plugins/aidd-context/skills/10-learn/actions/03-write.md b/plugins/aidd-context/skills/10-learn/actions/03-write.md new file mode 100644 index 00000000..b9558365 --- /dev/null +++ b/plugins/aidd-context/skills/10-learn/actions/03-write.md @@ -0,0 +1,24 @@ +# 03 - Write + +Write each approved lesson to the destination the user chose. + +## Input + +The approved plan from action 02. + +## Output + +The created or updated files, and a summary table. + +## Process + +1. **Write by destination:** + - **Memory.** Update the matching memory file at the root of the bank. Touch only the relevant section, and replace an entry the lesson supersedes rather than adding a contradicting one. Preserve the user's edits. + - **Decision.** Write a record in `aidd_docs/memory/internal/decisions/` from `@../assets/decision-template.md`, named by a short slug. Create the folder if absent. + - **Rule.** Hand the convention to the rule generator. Never write a rule file here. + - **Skill.** Hand the intent to the skill generator. Never write a skill file here. +2. **Report.** A table: lesson, destination, action taken (created, updated, or handed off). + +## Test + +- Every approved lesson appears in the table. A decision lands as a record in the decisions folder. No rule or skill file was written by learn, and nothing was written into AIDD's own scaffold. diff --git a/plugins/aidd-context/skills/10-learn/actions/04-sync.md b/plugins/aidd-context/skills/10-learn/actions/04-sync.md new file mode 100644 index 00000000..44f74ade --- /dev/null +++ b/plugins/aidd-context/skills/10-learn/actions/04-sync.md @@ -0,0 +1,21 @@ +# 04 - Sync + +Refresh the project memory block in every context file so the new and updated memory files are referenced. + +## Input + +The summary table from action 03, confirming at least one memory file changed. + +## Output + +Each memory block lists the current memory files, and the memory index is refreshed. + +## Process + +1. **Run.** Execute the memory-sync script (`update_memory.js` in the plugin's `hooks/`) to inject the references and refresh the memory index. +2. **Guard.** On a non-zero exit, print the error and stop. Tell the user to confirm the memory bank holds a file and that `node` is available. +3. **Report.** Print how many context files were updated and how many references went into each block. + +## Test + +- Each context file's memory block references every file in the memory bank, and the report names the files updated rather than a fixed count. diff --git a/plugins/aidd-context/skills/10-learn/assets/adr-template.md b/plugins/aidd-context/skills/10-learn/assets/adr-template.md deleted file mode 100644 index 7a87e8a7..00000000 --- a/plugins/aidd-context/skills/10-learn/assets/adr-template.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: adr -description: Architecture Decision Record template -argument-hint: N/A ---- - -# Architecture Decision Record (ADR) - -This file contains the key architectural decisions made during the project, along with their context and consequences. - -## Decision Log - -| Date | ID | Title | Consequences | -| ------- | ------- | ------------------------------------ | --------------------------- | -| !`date` | DEC-001 | [Decision Title](./#<date_id_title>) | [Brief consequence summary] | - -<!-- -IMPORTANT: THOSE ARE RULES FOR AI, DO NOT USE THOSE INTO FILLED TEMPLATE. - -- Date: use !`date` to get current date -- ID: use format DEC-XXX, incrementing number for each new decision -- Title: link to the decision file in ./decisions/ folder, ultra concise (max 8 words) -- Consequences: extremely brief summary of consequences, no filler words ---> diff --git a/plugins/aidd-context/skills/10-learn/assets/decision-template.md b/plugins/aidd-context/skills/10-learn/assets/decision-template.md index 02b79167..2d191865 100644 --- a/plugins/aidd-context/skills/10-learn/assets/decision-template.md +++ b/plugins/aidd-context/skills/10-learn/assets/decision-template.md @@ -1,45 +1,20 @@ ---- -name: decision -description: Individual decision record template -argument-hint: <title> ---- +# <Decision title> -# Decision: <title> - -| Field | Value | -| ------- | -------------- | -| ID | DEC-XXX | -| Date | !`date` | -| Feature | <feature-name> | -| Status | Accepted | +- Date: <YYYY-MM-DD> +- Status: Accepted ## Context -<Why was this decision needed?> +<What forced a choice. The problem and the constraints behind it.> ## Decision -<What was decided?> +<What was chosen, in one or two sentences.> -## Alternatives Considered +## Alternatives -| Alternative | Pros | Cons | Rejected because | -| ----------- | ---- | ---- | ---------------- | -| <alt1> | ... | ... | ... | +<The options considered, and why each one lost.> ## Consequences -<What are the results?> - -<!-- -IMPORTANT: THOSE ARE RULES FOR AI, DO NOT USE THOSE INTO FILLED TEMPLATE. - -- ID: use format DEC-XXX, incrementing number for each new decision -- Date: use !`date` to get current date -- Feature: name of the feature or component this decision relates to -- Status: Accepted | Deprecated | Superseded by DEC-XXX -- Context: 2-3 sentences explaining why this decision was needed -- Decision: 1-2 sentences stating what was decided -- Alternatives: only include alternatives that were seriously considered -- Consequences: positive and negative outcomes of this decision ---> +<What this makes easier, what it makes harder, what it locks in.>