feat(aidd-context): add Persistent Learning from mistakes with lessons.md

Start by reading plugins/aidd-context/skills/10-learn/SKILL.md, its actions/03-assess.md, references/destinations.md, and hooks/update_memory.js, then map the proposed lessons arguments and SDLC handoffs to existing extension points. Review the current regression and behavioral-evaluation structure for the context plugin. Done means the learning lifecycle, review safeguards, persistence boundaries, and lessons.md integration match the proposal and are covered by documentation and tests.

1. Summary and motivation

Introduce a persistent learning loop that lets AIDD capture meaningful errors, preserve their causes and corrections, and reuse approved lessons in later tasks and sessions.

The intended workflow is:

Observe an error or correction
             ↓
Capture evidence and a candidate lesson
             ↓
Check existing knowledge and contradictions
             ↓
Human review: approve, modify, or reject
             ↓
Persist the approved lesson in its appropriate home
             ↓
Read and apply it before relevant future work
             ↓
Verify, refine, supersede, or retire it

The objective is to reduce repeated mistakes, repeated debugging, and repeated user corrections. Recording an incident is useful only if the resulting knowledge can influence subsequent work.

This proposal uses a hybrid model:

• Automatic capture is explicitly enabled per project.
• Captured candidates remain inactive until human review.
• Approved lessons become available across sessions.
• Promotion into an existing rule, memory entry, contract, ADR, or skill follows AIDD’s existing learning workflow.

The problem

An agent can encounter a project-specific failure, investigate it, apply the correct fix, and then repeat the same failure in another session because the relevant knowledge remained in conversation history.

Examples include:

• Reusing a command that is unsuitable for the repository.
• Editing a generated artifact instead of its source.
• Repeating a previously rejected architectural approach.
• Missing a prerequisite already discovered during debugging.
• Reintroducing a testing mistake identified in an earlier review.
• Applying a workaround outside the conditions where it was validated.

These failures create several costs:

Cost	Consequence
Repeated investigation	Contributors spend time rediscovering an established explanation.
Repeated corrections	Users must restate the same project constraint.
Inconsistent sessions	Different agents or tools reach incompatible conclusions.
Lost rationale	A future contributor sees a convention without understanding the failure it prevents.
Fragile handoffs	Useful knowledge depends on access to a particular conversation.
Accumulating context	Teams compensate by adding increasingly broad instructions to their entrypoint files.

Persistent learning should turn a verified correction into reusable project knowledge while keeping that knowledge scoped, reviewable, and maintainable.

Research and conceptual basis

External memory and feedback. The Reflexion research describes agents using textual reflections on feedback as memory for subsequent attempts, without updating model weights. It supports the principle of learning from recorded failures, but its benchmark results should not be presented as expected results for AIDD. Reflexion paper

Persistent files and failure evidence. Manus describes using the filesystem as external memory and preserving failed actions and their observations so agents can adapt. For AIDD, this motivates retaining a concise explanation and evidence rather than merely recording the successful final action. Manus context engineering article

Existing product practice. Claude Code documents persistent instructions and agent-written memory based on corrections and discoveries. Its documentation also distinguishes contextual guidance from deterministic enforcement. AIDD should provide a project-owned learning workflow across its supported tools rather than depend on one host’s private memory. Claude Code memory documentation

Concrete file-based practice. Public repositories already use Markdown learning logs containing an identifier, context, lesson, and action. This illustrates the convention; it does not establish a universal lessons.md specification. Example learning log

In this issue, “persistent learning” means preserving and reusing external project knowledge. It does not mean fine-tuning, changing model weights, or guaranteeing that an agent will always obey a lesson.

2. Existing AIDD behavior and proposed scope

Prior art in this repository

AIDD already implements important parts of this capability:

• 10-learn captures durable project knowledge from conversations, files, diffs, and reviews. Its current contract requires an approved plan before writing. Current skill, lines 1–35
• Its assessment action scores candidates, reconciles existing knowledge, and asks the user to approve, modify, or skip them. Assessment action, lines 13–19
• Its destination model already covers memory, ADRs, contracts, rules, and skills. Existing destinations
• Project-memory synchronization exposes root memory files separately from internal and external references read on demand. It refreshes references; it does not itself guarantee that every host reads their contents. Memory synchronization

The missing capability is a complete mistake-learning lifecycle: automatic candidate capture, a clearly separated review queue, explicit recall before relevant work, and maintenance when knowledge changes.

This should extend existing capabilities rather than introduce an independent learning subsystem.

Deliverables

1. A project-owned lessons.md containing concise, approved lessons.
2. An internal learning log preserving candidates, incident evidence, and lifecycle history.
3. An extension of 10-learn covering capture, review, recall, and maintenance.
4. Integration with project-memory setup and synchronization.
5. Integration with relevant SDLC handoffs.
6. Documentation, templates, regression coverage, and behavioral evaluation scenarios.

Ownership

• aidd-context owns lesson production, assessment, persistence, and recall guidance.
• aidd-orchestrator sequences learning at appropriate handoffs and supplies relevant lessons to existing delegated work.
• Execution skills return findings and validation evidence; they do not implement their own learning policy.
• Memory hooks maintain deterministic wiring. They do not infer root causes from raw events.
• Telemetry remains optional and is not a prerequisite.

Related issues

• #801 — Document the Project Memory model and lifecycle: the canonical memory documentation should explain this addition.
• #897 — Validate a per-feature decision log: a feature log may supply evidence, whereas lessons preserve knowledge reusable beyond that feature. This proposal must work without that issue being implemented.
• #1018 — Preserve project-memory files on write failure: learning persistence must account for the existing write-safety concern.

3. Proposed behavior and interfaces

Storage and loading

Use two complementary artifacts:

aidd_docs/memory/
├── lessons.md             Approved, concise lessons relevant to future work
└── internal/
    └── lessons-log.md     Candidates, incident evidence, and review history

lessons.md belongs to the existing root-memory loading tier. The internal log remains available on demand and must not be imported in full at every startup.

The distinction is intentional:

• The active file answers: “What should a future agent remember and do?”
• The internal log answers: “What happened, what evidence supports the lesson, and what was decided?”

After promotion, the log references the canonical lesson or destination instead of maintaining a second current copy of the same instruction.

If an existing project document already owns the knowledge, update that document after approval. Do not create a competing rule in lessons.md.

Skill interface

Extend the existing learning skill with a dedicated lessons argument namespace:

Proposed invocation	Behavior
/aidd-context:10-learn lessons setup	Configure automatic capture and wire the learning artifacts.
/aidd-context:10-learn lessons capture <source>	Assess a specified source and record eligible candidates.
/aidd-context:10-learn lessons review	Review pending candidates through approve, modify, or reject decisions.
/aidd-context:10-learn lessons recall <task>	Read approved lessons and identify those applicable to the task.
/aidd-context:10-learn lessons maintain	Propose deduplication, corrections, promotion, supersession, and retirement.
/aidd-context:10-learn lessons disable	Disable automatic capture while preserving recorded knowledge.

These are proposed skill arguments, not new standalone CLI commands. Existing invocations using conversation, file, diff, and review retain their current meaning.

Automatic capture should reuse the same capture capability. It must not require users to invoke the command after every eligible correction.

Activation and authorization

Automatic capture is disabled until the user enables it for the project.

Setup explains and records the authorization: the agent may persist eligible candidate observations, but may not activate them as durable instructions without review.

This introduces a narrowly scoped exception to the current approved-write contract:

• Candidate capture may occur automatically after opt-in.
• Active lessons and changes to other knowledge destinations still require approval.
• Approval to capture is not approval to change project rules.

Store the capture policy in the managed header of lessons.md; do not introduce a separate configuration store for this feature.

Disabling automatic capture preserves both files and approved lessons. Removing or deactivating approved knowledge is a separate, explicit maintenance action.

Eligible capture events

Capture a candidate when the agent observes evidence of a reusable project-specific mistake, including:

• An explicit user correction.
• A confirmed review finding.
• A failed command with a subsequently validated explanation.
• A debugging discovery that changes the correct approach.
• A repeated incident showing that an existing lesson is incomplete.
• A handoff failure caused by missing project knowledge.

Capture once the useful evidence is available. Do not defer every capture until session termination.

A nonzero exit code alone is insufficient. Expected failing tests, temporary service outages, cancelled operations, and ordinary exploration are not automatically lessons.

If the cause remains uncertain, record that uncertainty explicitly. Do not invent a diagnosis or promote an unverified workaround.

Candidate content

Each candidate must contain enough information for a reviewer to evaluate it without reopening the original conversation:

Field	Purpose
Stable identifier	Track the candidate across reviews and updates.
First and latest observation dates	Establish when the evidence was observed.
Status	Distinguish pending, approved, rejected, superseded, and retired records.
Context and scope	Identify the affected subsystem, operation, or workflow.
Observed mistake	Describe the concrete failed behavior.
Evidence	Reference the correction, finding, output, or repository artifact.
Cause	State the supported explanation, or explicitly mark it unknown.
Correction	Describe what resolved the problem and how that was verified.
Proposed lesson	Express a bounded, actionable future behavior.
Suggested destination	Identify the narrowest appropriate existing owner.
Related knowledge	Reference duplicates, contradictions, or earlier lessons.
Review outcome	Record the approval, modification, or rejection when reviewed.

Personal judgments such as “the agent was lazy” are not technical causes. Replace them with observable behavior, such as “the agent edited the generated file without checking its generator.”

Review and promotion

Reuse the current assessment and reconciliation model.

Reviewers must be able to:

• Approve a candidate as written.
• Modify its wording, scope, or destination.
• Reject it with a short reason.
• Leave it pending when evidence is insufficient.
• Merge it into existing knowledge.
• Supersede or retract earlier knowledge explicitly.

Repeated occurrence increases the evidence available to reviewers. It does not automatically grant approval.

Do not add a mandatory approval interruption after every capture. Pending candidates can be reviewed together through an explicit review action or an appropriate user interaction.

Active lesson format

An active lesson should state:

1. When it applies.
2. What action to take.
3. Why that action matters.
4. How to verify the result.
5. Where its evidence or canonical owner can be found.

Illustrative example:

## LRN-<stable-id> — Edit generator inputs

- Applies to: changes to generated client code.
- Action: locate and change the generator input, then regenerate the client.
- Reason: direct edits are overwritten by subsequent generation.
- Verify: regeneration produces the intended change without manual output edits.
- Evidence: internal/lessons-log.md#<record-anchor>

This is an example of the format, not a claim about a specific AIDD-generated client.

Avoid entries such as “be careful,” “test more,” or “always use this workaround.”

Recall and application

Before planning or executing relevant work, the agent reads the active lessons and selects those whose scope matches the task.

For relevant lessons, it must:

• Verify that referenced files and prerequisites still exist when needed.
• Apply the stated behavior within its documented scope.
• Preserve the verification step.
• Report a material conflict rather than silently choosing an interpretation.

An approved lesson does not override current user instructions, enforced project contracts, or newer verified evidence.

A Markdown reference alone must not be treated as proof that a host loaded the file. Tools without native import expansion need explicit read instructions.

Existing delegated tasks receive the relevant approved lessons in their handoff. This feature does not authorize additional agent spawning.

Maintenance and context budget

Keep the active file focused on current, useful knowledge.

For automatically maintained content, use a default budget of 200 lines and 16 KiB, whichever is reached first. These are project defaults, not claims about model limits.

When a proposed promotion exceeds the budget:

• Preserve the candidate.
• Explain the budget conflict.
• Propose consolidation or relocation to an existing owner.
• Do not silently truncate or delete lessons.

Historical incidents and detailed evidence remain in the on-demand log.

Example lifecycle

1. An agent edits a generated artifact.
2. A user explains that the generator input is the correct source.
3. After regeneration validates the correction, the agent records a pending candidate.
4. A later review approves a narrowly scoped lesson.
5. The next session reads the active lesson before touching the same generated area.
6. The agent changes the generator input and verifies the generated output.
7. If the generation workflow is later removed, maintenance proposes retiring the lesson.

The successful outcome is observable behavior in step 6, not merely the existence of a Markdown entry.

4. Acceptance criteria

A. Setup and backward compatibility

• PL-01: Automatic capture remains disabled in a project that has not explicitly enabled it.
• PL-02: Setup explains the distinction between candidate capture and active knowledge.
• PL-03: Setup creates or reconciles both learning artifacts without overwriting user-authored content.
• PL-04: Repeating setup produces no duplicate sections, references, or instructions.
• PL-05: The presence of an unrelated pre-existing lessons.md does not silently enable automatic capture.
• PL-06: Disabling capture preserves existing candidates, review outcomes, and approved lessons.
• PL-07: Existing learning invocations retain their behavior and approval requirements.
• PL-08: Projects without learning artifacts continue to use existing AIDD workflows successfully.

B. Candidate capture

• PL-09: With capture enabled, an explicit project-specific user correction produces an eligible candidate without a separate capture request.
• PL-10: A confirmed review finding can produce a candidate linked to its evidence.
• PL-11: A debugging discovery distinguishes the initial failure from the validated correction.
• PL-12: An expected failing test does not automatically become a lesson.
• PL-13: An unexplained command failure does not become a confirmed root-cause statement.
• PL-14: An uncertain cause remains explicitly uncertain in the captured record.
• PL-15: A routine retry with no reusable discovery creates no candidate.
• PL-16: Capture occurs when sufficient evidence becomes available and does not rely exclusively on a session-end hook.

C. Record quality and evidence

• PL-17: Every candidate has a stable identifier, status, scope, observation date, and evidence reference.
• PL-18: The observed failure and proposed future behavior are distinguishable.
• PL-19: A claimed successful correction includes its validation evidence.
• PL-20: Missing evidence is reported rather than fabricated.
• PL-21: Candidate wording identifies observable behavior rather than attributing motives or personality.
• PL-22: A proposed lesson states the conditions under which it applies.
• PL-23: Generic statements without an actionable behavior are rejected or rewritten before promotion.
• PL-24: Reprocessing the same source does not create another copy of the same candidate.

D. Human review and activation

• PL-25: Automatically captured candidates remain pending until reviewed.
• PL-26: Pending and rejected candidates are not presented as active instructions.
• PL-27: Review supports approve, modify, reject, and leave-pending outcomes.
• PL-28: Approval identifies the accepted wording, scope, and destination.
• PL-29: Modified approval writes the reviewed wording rather than the original proposal.
• PL-30: A rejected candidate remains distinguishable from a candidate awaiting review.
• PL-31: Repetition alone does not approve a candidate.
• PL-32: Automatic capture does not introduce a mandatory approval pause after every recorded event.

E. Reconciliation and canonical ownership

• PL-33: Assessment checks existing memory, relevant rules, contracts, ADRs, and skills before proposing a new active entry.
• PL-34: Already-covered knowledge is referenced without creating a parallel instruction.
• PL-35: A refinement updates the existing owner after approval.
• PL-36: Contradictory proposals identify the existing knowledge they would change.
• PL-37: Supersession records the relationship between the earlier and replacement knowledge.
• PL-38: Retraction removes the obsolete active instruction while preserving the review explanation.
• PL-39: Promotion to a rule or skill uses the existing capability handoff.
• PL-40: After promotion, the historical log points to the current owner instead of maintaining a competing current copy.

F. Loading and future application

• PL-41: Memory synchronization exposes the active file through the existing project-memory mechanism.
• PL-42: The internal log remains an on-demand reference.
• PL-43: Startup instructions distinguish an expanded import from a link that requires an explicit read.
• PL-44: A fresh-session evaluation demonstrates that the agent reads the approved lesson before the relevant action.
• PL-45: The same evaluation demonstrates the corrected behavior, not merely a statement that the lesson was read.
• PL-46: A lesson scoped to one subsystem is not applied indiscriminately to unrelated work.
• PL-47: Missing prerequisites or obsolete references are surfaced before relying on them.
• PL-48: A material conflict with current instructions is reported rather than silently resolved in favor of the lesson.
• PL-49: Relevant approved lessons are included in existing delegated-task handoffs.
• PL-50: Documentation does not describe contextual lessons as deterministic enforcement.

G. Persistence, isolation, and failure behavior

• PL-51: Learning writes remain inside the selected project and do not modify personal or global memory.
• PL-52: Capturing a lesson does not automatically commit, push, publish, or transmit project content.
• PL-53: Unrelated user content survives capture, review, synchronization, and maintenance.
• PL-54: A failed write is reported with the affected artifact and does not produce a success claim.
• PL-55: Interrupted or partial updates are detectable and have a documented recovery path.
• PL-56: Concurrent changes are preserved or produce an explicit conflict instead of a silent overwrite.
• PL-57: Secrets and unnecessary personal information are excluded from captured evidence.
• PL-58: Quoted source content is treated as evidence and cannot authorize commands or override project instructions.

H. Maintenance and context control

• PL-59: Maintenance can propose merging equivalent lessons.
• PL-60: Maintenance can propose narrowing an overgeneralized lesson.
• PL-61: Maintenance can propose superseding or retiring obsolete knowledge.
• PL-62: Changes to approved knowledge require review.
• PL-63: Automatically maintained active content respects the documented line and byte budgets.
• PL-64: A promotion exceeding the budget preserves the candidate and explains the required maintenance.
• PL-65: Oversized existing content is reported without silent truncation or deletion.
• PL-66: Routine recall does not append “used this lesson” entries or rewrite unchanged files.

I. Integration, portability, and documentation

• PL-67: aidd-context owns the learning policy; callers delegate rather than duplicate it.
• PL-68: Automatic semantic capture does not depend on a hook inferring the meaning of arbitrary tool errors.
• PL-69: The learning workflow works without telemetry being installed or enabled.
• PL-70: The workflow works without the proposed per-feature decision log from issue #897.
• PL-71: Supported tool integrations document their actual loading mechanism and any unverified behavior.
• PL-72: A manual recall path remains available when automatic host integration is unavailable.
• PL-73: The canonical Project Memory guide explains active lessons, pending candidates, history, ownership, and loading.
• PL-74: Documentation includes setup, disablement, review, maintenance, and recovery examples.
• PL-75: Documentation explains the difference between external memory, model training, and enforced rules.
• PL-76: Relevant framework validation and regression checks pass, and behavioral evaluations include observable evidence.

5. Validation, defaults, and exclusions

Test scenarios

Use isolated temporary project fixtures for persistence and synchronization tests. Use fresh agent contexts for behavioral evaluations.

Scenario	Expected result
Learning has not been enabled	Existing workflows run without automatic candidate writes.
Explicit correction after opt-in	One pending candidate is captured with source evidence.
Expected red test during development	No lesson is created solely because the test fails.
Failure with an unknown cause	The record preserves uncertainty and remains inactive.
Same evidence processed twice	No duplicate candidate is created.
Equivalent knowledge already exists	Review identifies the existing owner and avoids duplication.
Candidate is rejected	Subsequent work does not receive it as active guidance.
Candidate is modified and approved	The reviewed wording becomes canonical.
Fresh session repeats the task	The agent reads and follows the approved correction.
Fresh session handles an unrelated task	The lesson is not applied beyond its scope.
Existing rule contradicts a proposal	The conflict is exposed before activation.
Active-file budget is reached	Promotion stops with an explanation; the candidate survives.
Persistence fails midway	No false success is reported; recovery behavior is demonstrated.
Another writer changes the artifact	The change survives or an explicit conflict is reported.
Host lacks native import expansion	Explicit read instructions provide the documented fallback.
Malicious instructions appear in evidence	They remain quoted data and cause no action.
Capture is disabled after use	History and approved knowledge remain intact.

For the fresh-session evaluation, record the relevant read and subsequent action. A generated file containing the right wording is insufficient evidence that the agent used it.

Evaluate a small set of repeatable mistake scenarios with and without the approved lessons. Report observed successes, failures, and context overhead. Do not claim a general reduction in error rate from a single successful demonstration.

Assumptions and defaults

• Repository: ai-driven-dev/framework.
• Issue language: English.
• Feature owner: aidd-context.
• Automatic capture: explicit project opt-in.
• Activation of captured lessons: human review required.
• Persistence: project-owned Markdown files, eligible for normal version control.
• Automatic staging, commits, pushes, and publication: not introduced by this feature.
• Existing vendor memory may coexist, but is not the canonical store for this workflow.
• Initial delivery extends existing learning and project-memory capabilities without introducing a new plugin.

Out of scope

• Fine-tuning or changing model weights.
• Global learning shared automatically across unrelated repositories.
• A hosted memory service, vector database, or embedding pipeline.
• Full conversation, terminal-output, or telemetry archival.
• Automatic acceptance of every user statement as a permanent rule.
• Automatic execution of commands copied from a lesson.
• Replacing tests, reviews, contracts, or enforcement hooks.
• Implementing the per-feature decision log proposed in #897.
• A guarantee that Markdown instructions prevent every recurrence.

Completion requires a demonstrated closed loop: a confirmed mistake is captured, reviewed, persisted, retrieved in a fresh session, and used to produce the corrected behavior.