haidrrrry/loop-engineering-skills

Loop Memory

Reflexion-style verbal memory: the agent reflects on each attempt in writing, stores the reflection, and reads recent reflections before acting. Research (Shinn et al., 2023) shows this mechanism — reflect, store, re-read — beats blind retrying by wide margins (+22% on decision tasks over 12 trials, +11% on code) and beats memory-without-reflection by 8 points. The gain comes from written reasons, not from retrying harder.

The protocol

Before acting (every task)

1. Read .loop/LESSONS.md.
2. Apply the Standing rules section unconditionally.
3. Read the 3 most recent entries. If any is relevant to the current task, state in one line how it changes your approach. If none is relevant, proceed — do not force it.

After acting (every attempt, pass or fail)

Append exactly one entry in the file's format:

## [date] — [task, 5 words max] — PASS|FAIL
- What happened: [one line]
- Root cause / why it worked: [one line]
- Next time: [one specific, checkable instruction]

Quality bar for "Next time":

• ❌ "Be more careful with the database" — not checkable
• ✅ "Run npx prisma migrate deploy before any seed script" — checkable
• ❌ "Remember the API is tricky" — vague
• ✅ "The /users endpoint paginates at 50; always pass ?page= when counting"

Failure reflection, specifically

When an attempt failed, the reflection must answer: what did I believe that was wrong? Failed attempts usually come from a false assumption, not a typo. Name the assumption. That's the lesson.

Maintenance (when the file exceeds ~30 entries)

1. Read all entries oldest-first.
2. Any lesson that appears 2+ times graduates into Standing rules, rewritten as a single imperative line.
3. Delete the oldest 20 entries after graduation.
4. Never delete Standing rules without the user's approval.

What NOT to store

• Secrets, keys, tokens, personal data — never, even if they caused the failure.
• Narration ("I then tried X, after which Y…") — store conclusions only.
• Duplicate lessons — if it's already there, don't re-add; consider graduating it.
• Blame or self-criticism — lessons are instructions, not feelings.

Failure modes to avoid

• Memory theater: writing entries but never reading them. The read step is the value; the write step alone is a diary.
• Overfitting to one incident: a one-off environment hiccup is not a lesson. If it can't recur, don't record it.
• Unbounded growth: a 200-entry file no one reads is dead memory. Compress.