mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-11 17:56:37 +08:00
ryan
118 lines
3.9 KiB
Markdown
118 lines
3.9 KiB
Markdown
# 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.
|