# Learning Ledger Version: 1.0.0 ## Purpose This file stores **candidate reusable lessons** discovered during real project work. It sits between: ```text OBSERVATION ``` and: ```text 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: ```text OBSERVE ↓ CAPTURE ↓ REUSE / REPEAT? ↓ PROMOTE ``` instead of: ```text 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. ```text --- ## 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: ```text one incident uncertain cause weak evidence possible coincidence ``` Do not usually promote a LOW-confidence lesson. --- ## MEDIUM Use when: ```text 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: ```text 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: ```text Repetition Count: 1 ``` Later: ```text Repetition Count: 2 ``` Then: ```text 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: ```text 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: ```text most agents most tasks repository-wide agent behavior ``` Example: ```text Always inspect existing database migration scripts before designing a new migration. ``` --- ## CLAUDE.md Use when the lesson specifically concerns Claude behavior. Example: ```text Claude should inspect the diff after broad search-and-replace edits. ``` --- ## Existing Skill Prefer this when the lesson extends an existing procedure. Example: ```text mirror-audit should check service-account permissions during deployment reviews. ``` --- ## New Skill Create only when: ```text 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: ```text Production deployments must target IIS App Pool ScheduliciousPool. ``` That is not a general agent rule. --- # 9. Rejection Reject candidate learning when: ```text 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: ```text 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 ```text .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: ```text expected rows imported rows rejected rows ``` ### Scope SKILL-SPECIFIC ### Candidate Destination ```text .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 ```text .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 ```text CLAUDE.md ``` ### Confidence MEDIUM ### Repetition Count 2 ### Action PROMOTED --- # 15. Periodic Review Periodically review PENDING entries. For each entry decide: ```text 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: ```text 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: ```text Safe Windows Application Deployment ``` with: ```text 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: ```text "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: ```text "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: ```text 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: ```text User: "Don't use React for this application." ``` Do not infer: ```text "User never wants React anywhere." ``` Instead record the project-specific constraint if relevant. --- # 20. Learning Promotion Workflow ```text 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.