# Lessons system The lessons system is what separates autoresearch from a dumb mutation loop. It is the mechanism by which each overnight run starts smarter than the last. --- ## The compounding model ``` Night 1: 100 experiments → lessons-v1 written Night 2: reads lessons-v1 → avoids 20 known failures → 80 net-new experiments Night 3: reads lessons-v2 → avoids 35 known failures → faster convergence ... ``` Without the lessons system, every run starts from scratch. With it, runs compound — each failure is learned once and never repeated. --- ## File location and format File: `autoresearch-lessons.md` in your project root. Add to `.gitignore` — this is a working file for the agent, not source code. ```markdown # Autoresearch lessons — Generated by the autoresearch skill. Do not edit manually. Last updated: ## Lesson 1 — iterations 1–5 **Pattern**: **Why it worked**: **Conditions**: **Anti-pattern**: **Metric delta**: ## Lesson 2 — iterations 6–10 ... ``` --- ## When to write lessons Append a new lesson after every 5 KEPT iterations (not every 5 total iterations). Lessons should only describe what worked. Failed patterns are captured implicitly — if a pattern never generates a kept iteration, it never generates a lesson, and the loop naturally deprioritises it via Phase 2's "different from last 3 attempts" rule. --- ## What makes a good lesson **Good** (specific, mechanistic, conditional): ``` **Pattern**: Defer non-critical third-party scripts using loading="lazy" **Why it worked**: Removes scripts from the critical render path, reducing Time to Interactive without affecting functionality **Conditions**: Applies to analytics, chat widgets, social embeds — not to scripts required for initial page render **Anti-pattern**: Lazy-loading scripts that are called in the first 500ms of page load caused layout shifts and broke interactions **Metric delta**: +6.8% Lighthouse performance score across 3 iterations ``` **Bad** (vague, not actionable): ``` **Pattern**: Make things faster **Why it worked**: It improved performance **Conditions**: When performance is bad **Anti-pattern**: When it makes things worse ``` --- ## How to read lessons at the start of a run 1. Read the full file — do not skip old lessons even if they seem stale. 2. For each lesson, assess: does this pattern still apply given the current state of the codebase? If the code it describes has been significantly refactored, downweight it. 3. Extract the top 2-3 highest-delta patterns. These are your first hypotheses unless the results log shows they have already been exhausted. 4. Extract the anti-patterns. These are your first exclusions — do not generate hypotheses that match these patterns. --- ## Cross-project lessons For teams running autoresearch across multiple similar projects (e.g. multiple Next.js apps), consider maintaining a shared lessons file at `~/.autoresearch/global-lessons.md`. At the start of a run, read both the project-level and global lessons. Project-level lessons take precedence when they conflict with global ones. This is optional but significantly accelerates convergence on new projects that share a tech stack with already-researched ones. --- ## Lessons file maintenance - Do not manually edit the lessons file during a run — the agent reads it at the start of each run and its contents influence hypothesis generation. - After a long run (100+ iterations), review the file and remove lessons that are no longer applicable (e.g. they describe code that no longer exists). Add a comment explaining why the lesson was removed. - The lessons file is cumulative — never delete lessons, only annotate them as superseded if a newer lesson contradicts them.