cao-learning

# CAO Self-Learning

CAO workflows can improve as they repeat: outcomes you report feed a
retrospector agent that distills durable lessons into memory, and those
lessons reach future sessions automatically. Your job depends on your role.

All of this is opt-in infrastructure. **If `report_outcome` or a memory tool
returns `disabled: true`, skip it silently and continue your task** — learning
is off for this run (often deliberately, e.g. a control run) and that is
expected, not an error.

## If you are a SUPERVISOR

### Report an outcome after each meaningful unit of work

One `report_outcome` call per completed step, delegated task, or work item —
after validation/review, not before:

```
report_outcome(
    task_label="convert package CustomerETL (iteration 2)",
    success=false,
    workflow_name="ssis-migration",
    agent_profile="transformer",           # who did the work (defaults to you)
    score=40,                              # optional 0-100 metric if you have one
    friction_notes="Lookup with partial cache emitted an invalid join; "
                   "improver patched the cache-mode mapping."
)
```

Rules for `friction_notes`:
- 1–3 sentences, **conclusions only** — the root cause, not the story.
- NEVER paste transcripts, logs, stack traces, file contents, or secrets.
- Empty string on a clean pass is fine; the success flag already carries signal.

Report failures faithfully — failed iterations are the most valuable learning
signal. Do not skip reporting because a step went badly.

### Dispatch the retrospector at natural boundaries

After each completed work item (a package, a feature, a review cycle) — not
after every step — hand off to the `retrospector` agent:

```
"Retrospect on session <session_name>, workflow <workflow_name>,
 item <item name>. Agents involved: <profiles>."
```

Wait for its one-line summary (outcomes read, lessons stored) and record it in
your run log. If no retrospector profile is available, skip this step.

### Pass lessons downstream

Your injected `<cao-memory>` block may contain lessons from previous runs.
When a lesson's `Applies when:` clause matches the task you are delegating,
include it in your handoff message — workers also receive their own
agent-scope lessons, but your routing helps.

## If you are a WORKER

1. **Apply injected lessons first.** Before working, scan your `<cao-memory>`
   block and any `## Learned Patterns` section of your own instructions for
   lessons whose `Applies when:` clause matches the current task. Apply them
   before falling back to first principles.
2. **Store new lessons immediately** when you discover something durable — a
   mapping that works, a trap that recurs, a tooling quirk:

   ```
   memory_store(
       content="Preserve a Lookup transform's cache mode instead of defaulting "
               "to a full-table read. Applies when: translating a Lookup whose "
               "CacheType is not full cache.",
       scope="agent",
       memory_type="feedback",
       key="honor-lookup-cache-mode"
   )
   ```

   Format contract: 1–2 sentence conclusion, then `Applies when: <trigger>`.
   The trigger clause is how future curators match your lesson to a task.
3. **Correct, don't accumulate.** If a stored lesson proves wrong, re-store
   the corrected text under the SAME key (or `memory_forget` it). Never store
   a contradicting lesson under a new key.

## If you are the RETROSPECTOR

Follow your profile (`retrospector.md`). Read outcomes with the
`list_outcomes` tool; store worker-craft lessons with
`store_lesson(target_agent_profile=..., content=...)` — NOT `memory_store`,
which files agent-scope lessons under YOUR profile, where the worker will
never see them. The quality bar, in brief: 0–3 lessons per retrospection,
each supported by a concrete outcome, actionable, general enough to recur,
under 400 characters, ending with `Applies when:`. "No lessons" is a valid
and often correct answer.

## What happens to lessons afterwards

- Lessons are ordinary agent-scope memories: injected into future sessions,
  recalled on demand (each recall reinforces them), lint-checked for
  contradictions, audited.
- An operator may promote reinforced lessons into your profile's
  `## Learned Patterns` block with `cao memory promote` — that block is
  CAO-maintained; treat its contents as instructions, and don't edit it
  by hand.