| name | reflector |
| description | Structured self-improvement system for AI agents. Implements a reflection loop that transforms interactions into learning through outcome tracking, daily reviews, weekly principle refinement, and measurable improvement. Use when setting up systematic agent learning, creating PRINCIPLES.md frameworks, scheduling reflection cron jobs, or logging task outcomes for pattern recognition.
|
Reflector
A system for getting better at what you do, systematically, over time.
The Problem
Most agents accumulate experience but don't learn from it. They make the same mistakes, miss the same patterns, and never refine their judgment. Memory files capture what happened. Reflector captures what it means.
The Solution
A feedback loop:
ACT -> OBSERVE -> EXTRACT -> REFINE -> MEASURE -> ACT
- Act - Do work normally
- Observe - Daily review classifies outcomes from all channels
- Extract - Identify patterns across accumulated observations
- Refine - Update decision-making principles based on evidence
- Measure - Track whether changes actually improve outcomes
Improvement happens through better principles and sharper self-knowledge, not model retraining.
Setup
Step 1: Initialize
Run from your workspace root:
node /path/to/reflector/scripts/init-reflector.js
This creates:
PRINCIPLES.md - Your decision-making framework (if none exists)memory/reflector/outcomes.jsonl - Structured outcome logmemory/reflector/principles-history.jsonl - Principle change trackingmemory/reflector/weekly-summaries/ - Weekly review outputs
Run --help for options, --dry-run to preview.
Step 2: Create cron jobs
Use the OpenClaw cron tool to create two jobs. The prompt text is in the
prompts/ directory - read the file and use its contents as the agentTurn message.
Daily review (reads prompts/daily-review.txt):
- Schedule:
30 3 * * * (3:30 AM, adjust to your timezone)
- Session: isolated
- Delivery: none (silent unless something needs human attention)
Weekly refinement (reads prompts/weekly-refinement.txt):
- Schedule:
0 3 * * 0 (3:00 AM Sunday)
- Session: isolated
- Delivery: announce (sends summary to human)
Step 3: Integrate outcome logging
After significant tasks where you receive clear feedback, log the outcome:
node /path/to/reflector/scripts/log-outcome.js \
--task "Drafted client email" \
--quality edit \
--delta "Human shortened technical explanation" \
--lesson "Executives want implications, not details"
When to log: Not every task. Log when there's a clear feedback signal -
a correction, a rewrite, explicit praise, or conspicuous silence on something
important. The daily review also catches signals you miss.
Quality types: correction, edit, praise, silence, unknown
The --lesson flag is where the value lives. A log without a lesson is
just a record. A log with a lesson is raw material for principles.
How Principles Work
Good principles resolve tensions. They tell you what to do when multiple
good options conflict.
Good: "Confidence should scale with evidence" - guides the accuracy/speed tradeoff
Bad: "Be accurate" - says nothing about what to do when accuracy costs time
Each principle needs:
- Origin - What happened that created this principle
- Evidence - Specific outcomes that support it
- Application - When and how to apply it
See example-principles.md for what a
mature PRINCIPLES.md looks like after a month of use. See
templates.md for the full framework.
Quality Gates
Principles don't get added on impulse. The system enforces:
- Evidence threshold - 3+ supporting outcome observations before adding
- Tension test - Does it guide decisions when multiple good options conflict? (A principle that just says "be accurate" fails this - it doesn't help when accuracy conflicts with speed.)
- Specificity test - Would this change observable behavior?
- Uniqueness test - Not already covered by existing principles?
Running Tests
npm test
Uses Node's built-in test runner. No dependencies required.
Project Structure
reflector/
SKILL.md This file
README.md GitHub-facing documentation
LICENSE MIT
package.json Project metadata and scripts
prompts/
daily-review.txt Canonical daily cron prompt
weekly-refinement.txt Canonical weekly cron prompt
scripts/
init-reflector.js Setup script (idempotent)
log-outcome.js Outcome logging CLI
references/
methodology.md Why this approach works
templates.md PRINCIPLES.md framework and formats
example-principles.md Complete example after one month
cron-prompts.md Design decisions behind the prompts
tests/
init-reflector.test.js 40 tests covering all script logic
log-outcome.test.js
Deeper Reading
