skills: autoresearch

.agents/skills/autoresearch/references/lessons-system.md

@@ -0,0 +1,117 @@
+# 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 — <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
+
+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.