AI_AGENT_OS/.ai/state/LEARNINGS.md

Learning Ledger

Version: 1.0.0

Purpose

This file stores candidate reusable lessons discovered during real project work.

It sits between:

OBSERVATION

and:

PERMANENT AI-SYSTEM CHANGE

Not every observation should become:

• a new rule
• a new skill
• a new prompt
• an AGENTS.md update

The learning ledger allows evidence to accumulate first.

---

1. Core Principle

Use:

OBSERVE
   ↓
CAPTURE
   ↓
REUSE / REPEAT?
   ↓
PROMOTE

instead of:

OBSERVE
   ↓
IMMEDIATELY ADD PERMANENT RULE

This prevents instruction bloat.

---

2. What Belongs Here

Capture a learning candidate when real work reveals:

• repeated friction
• repeated user correction
• repeated implementation failure
• repeated debugging procedure
• a strong reusable solution
• missing verification
• missing project guidance
• a useful architectural convention
• an effective prompt technique
• a recurring tool problem
• an obsolete instruction
• a reusable automation opportunity

---

3. What Does Not Belong Here

Do not record:

• ordinary typos
• one-off syntax mistakes
• transient task context
• temporary file names
• facts already documented elsewhere
• generic observations with no action
• every successful command
• every minor correction

The ledger should contain signal.

---

4. Learning Entry Template

Copy this template for each candidate.

---

## YYYY-MM-DD — Short Descriptive Title

### Observed During

Describe the task or project context.

### Evidence

What actually happened?

Include evidence such as:

- repeated error
- user correction
- failed test
- successful repeated method
- manual workaround
- project convention

### Candidate Lesson

State the possible reusable lesson in one or two clear sentences.

### Scope

Choose one:

- GLOBAL AGENT
- MODEL-SPECIFIC
- PROJECT-SPECIFIC
- SKILL-SPECIFIC
- PROMPT-SPECIFIC
- TEMPLATE
- AUTOMATION
- PROJECT DOCUMENTATION
- UNKNOWN

### Candidate Destination

Examples:

AGENTS.md

CLAUDE.md

.ai/skills/existing-skill/SKILL.md

.ai/skills/new-skill/SKILL.md

.ai/prompts/example.md

.ai/templates/example.md

project documentation

none

### Confidence

LOW

MEDIUM

HIGH

### Repetition Count

1

Increase when the same lesson appears again.

### Action

PENDING

PROMOTED

REJECTED

REVISIT

### Promotion Reason

Complete only if promoted.

### Result After Reuse

What happened when the promoted improvement was used again?

### Related Changelog

Version or changelog entry, if applicable.

---

---

5. Confidence Guidelines

LOW

Use when:

one incident

uncertain cause

weak evidence

possible coincidence

Do not usually promote a LOW-confidence lesson.

---

MEDIUM

Use when:

pattern appeared more than once

cause is reasonably understood

lesson appears reusable

A MEDIUM lesson may justify a small skill or prompt improvement.

---

HIGH

Use when:

repeated evidence

clear user correction

reproducible failure

verified project convention

successful repeated procedure

HIGH-confidence lessons are strong candidates for promotion.

---

6. Repetition Count

Repetition count tracks how often the pattern appears.

Example:

Repetition Count: 1

Later:

Repetition Count: 2

Then:

Repetition Count: 4

Repeated evidence increases confidence.

Do not treat repetition count as the only criterion.

One serious verified failure may justify immediate action.

---

7. Promotion Decision

Before promoting a learning, check:

Is it reusable?

Is the cause understood?

Is the lesson actionable?

Does it already exist elsewhere?

Is the proposed destination correct?

Can we test the improvement?

Could the change create broader problems?

If not, leave it pending.

---

8. Promotion Destinations

AGENTS.md

Use when the lesson applies to:

most agents

most tasks

repository-wide agent behavior

Example:

Always inspect existing database migration scripts before designing a new migration.

---

CLAUDE.md

Use when the lesson specifically concerns Claude behavior.

Example:

Claude should inspect the diff after broad search-and-replace edits.

---

Existing Skill

Prefer this when the lesson extends an existing procedure.

Example:

mirror-audit should check service-account permissions during deployment reviews.

---

New Skill

Create only when:

procedure is reusable

trigger is recognizable

workflow is substantial enough

existing skills do not own it

---

Prompt

Use when the lesson concerns launching or structuring a repeated interaction.

---

Template

Use when the reusable asset is primarily structural.

---

Project Documentation

Use when the lesson is a project fact.

Example:

Production deployments must target IIS App Pool ScheduliciousPool.

That is not a general agent rule.

---

9. Rejection

Reject candidate learning when:

it was a one-off incident

the original diagnosis was wrong

it duplicates existing guidance

it creates more process than value

the project changed

testing shows the proposed improvement is worse

Do not delete the entry immediately.

A rejected lesson can provide useful historical context.

Mark:

Action: REJECTED

and explain why.

---

10. Example: Repeated Project Pattern

YYYY-MM-DD — ASP controllers require consistent initialization

Observed During

Several Classic ASP controller implementations.

Evidence

Four controllers required the same initialization sequence:

1. validate request
2. initialize model/service
3. handle initialization error
4. execute action
5. return normalized response

Candidate Lesson

Controller creation follows a stable reusable project pattern and should not be rediscovered each time.

Scope

PROJECT-SPECIFIC

Candidate Destination

.ai/skills/classic-asp-controller/SKILL.md

Confidence

HIGH

Repetition Count

4

Action

PROMOTED

Promotion Reason

The procedure occurred repeatedly and has a clear input/process/output structure.

Result After Reuse

Pending.

---

11. Example: Bad Candidate

YYYY-MM-DD — Missing semicolon

Observed During

JavaScript edit.

Evidence

A semicolon was accidentally omitted.

Candidate Lesson

Agents should remember semicolons.

Confidence

LOW

Repetition Count

1

Action

REJECTED

Reason

Ordinary isolated coding mistake. Existing syntax checking already handles this.

---

12. Example: Verification Improvement

YYYY-MM-DD — Import status needs row-count verification

Observed During

Automated CSV import into Access.

Evidence

The import command returned successfully even when some records were rejected.

Candidate Lesson

Successful command completion is insufficient verification for data imports.

Imports should compare:

expected rows

imported rows

rejected rows

Scope

SKILL-SPECIFIC

Candidate Destination

.ai/skills/access-csv-import/SKILL.md

Confidence

HIGH

Repetition Count

2

Action

PENDING

---

13. Example: Prompt Failure

YYYY-MM-DD — Planning prompt overproduces detail

Observed During

Several small bug fixes.

Evidence

The planning prompt generated long multi-section plans for changes involving one or two lines.

Candidate Lesson

Planning depth should scale with task complexity.

Scope

PROMPT-SPECIFIC

Candidate Destination

.ai/prompts/plan.md

Confidence

HIGH

Repetition Count

3

Action

PROMOTED

---

14. Example: Model-Specific Behavior

YYYY-MM-DD — Claude loads too many unrelated files

Observed During

Large repository investigation.

Evidence

Claude read broad directories despite the target subsystem being known.

Candidate Lesson

Claude should search first and expand file context incrementally.

Scope

MODEL-SPECIFIC

Candidate Destination

CLAUDE.md

Confidence

MEDIUM

Repetition Count

2

Action

PROMOTED

---

15. Periodic Review

Periodically review PENDING entries.

For each entry decide:

PROMOTE

KEEP PENDING

REJECT

MERGE WITH ANOTHER LEARNING

Look especially for several related entries that should become one generalized skill.

---

16. Merge Related Learning

Suppose the ledger contains:

PowerShell deployment failed because service wasn't stopped.

PowerShell deployment failed because App Pool was locked.

PowerShell deployment failed because files were still in use.

Instead of three skills, generalize:

Safe Windows Application Deployment

with:

pre-deployment checks

service/app-pool handling

file lock checks

deployment

restart

health verification

rollback

The generalized procedure is the useful asset.

---

17. Learning from Success

Do not capture only failures.

Useful successful observations include:

"This audit consistently catches migration problems."

"This three-step debugging process isolated the issue quickly."

"This template produces reliable project updates."

"This deployment validation catches configuration drift."

These can become:

• skills
• prompts
• templates
• tests

Success is training data for the AI-OS.

---

18. Learning from User Corrections

User corrections are high-value signals.

If the user repeatedly says:

"Don't use React in this project."

"Always use parameterized ADODB commands."

"Each street needs its own worksheet."

"Do not rewrite the whole file."

determine whether the correction represents:

task-specific instruction

project rule

persistent workflow preference

general agent improvement

Store it in the narrowest correct location.

---

19. Do Not Infer Too Much

A single correction does not automatically imply a universal rule.

Example:

User:
"Don't use React for this application."

Do not infer:

"User never wants React anywhere."

Instead record the project-specific constraint if relevant.

---

20. Learning Promotion Workflow

REAL WORK
   ↓
OBSERVATION
   ↓
LEARNING ENTRY
   ↓
MORE EVIDENCE?
   ↓
GENERALIZE
   ↓
CHOOSE DESTINATION
   ↓
MODIFY AI-OS
   ↓
SYSTEM AUDIT
   ↓
TEST
   ↓
CHANGELOG
   ↓
MARK PROMOTED

---

21. Ledger Hygiene

Keep this file useful.

Periodically:

• merge duplicate entries
• reject weak stale candidates
• mark promoted lessons
• update reuse results
• remove truly obsolete noise

Do not turn the ledger into an endless event log.

---

22. Initial State

No project-specific learning has been recorded yet.

The first entries should come from real project work.