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.

# Autoresearch lessons — <project name>
Generated by the autoresearch skill. Do not edit manually.
Last updated: <ISO date>

## Lesson 1 — iterations 1–5
**Pattern**: <the type of change that produced gains>
**Why it worked**: <mechanistic hypothesis — be specific>
**Conditions**: <codebase state where this applies>
**Anti-pattern**: <what failed when trying similar approaches>
**Metric delta**: <cumulative gain from this pattern, e.g. "+4.2%">

## 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

Read the full file — do not skip old lessons even if they seem stale.
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.
Extract the top 2-3 highest-delta patterns. These are your first hypotheses unless the results log shows they have already been exhausted.
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.

3.9 KiB Raw Blame History Unescape Escape