triggers:
  positive:
    - phrase: consolidate the pending Robium learning flags at this milestone
    - phrase: absorb these ready observations into the skills
    - phrase: show me the learning loop status without changing anything
  negative:
    - phrase: mine the upstream Nav2 repository for reusable patterns
      expect: mining
    - phrase: write a brand new Robium skill for depth cameras
      expect: skill-author
tasks: []

# Promoting a learning

Use the evidence ladder to keep cheap signals from becoming permanent advice.

## Queue flag to observation

- A queue flag is only a pointer into a transcript. Discard context-free shell
  noise and expected probes.
- Record a finding only when the source shows what was expected, what happened,
  and which skill or `[none]` is implicated.
- One user correction can be strong evidence. Otherwise prefer two independent
  occurrences or a complete failure/fix/check trail.
- An official source can support mined knowledge when it directly matches the
  claim and current platform.
- Missing proof stays `tentative`; uncertainty is not a reason to rush an edit.

The observation schema and legal statuses in `learnings/observations/README.md`
are the source of truth.

## Observation to skill

- Only `status: ready` is eligible for absorption.
- Re-read the cited transcript or source; do not absorb a summary from memory.
- Find the lowest skill that owns the decision. Split a finding when routing
  belongs to an umbrella skill but mechanics belong to a tool skill.
- Make the smallest edit that carries the knowledge, and remove superseded or
  duplicated guidance in the same change when safe.
- Keep exact values attached to their observed robot, platform, workload, and
  verification conditions.
- Edit the live skill directly with the normal repository editing tools. In the
  same reviewed change, mark the observation `absorbed YYYY-MM-DD` only after
  the guidance and its relevant checks have landed. The old anchor/version
  delta applier remains only for historical artifacts and experiments.

## Review

- Show the observation, owner, intended edit, and evidence together.
- External contributors and unattended runs stop at a human-reviewed PR.
- A maintainer's direct-edit authorization applies only to the current task and
  does not authorize pushes, publication, deployment, or paid work.

# Refining the catalog

Report findings before changing files. A clean pass should produce no churn.

## Remove harmful or unused guidance

- Start with user corrections and observations showing that a rule caused a
  bad decision.
- Remove advice that has no surviving use case rather than surrounding it with
  exceptions.
- Preserve the evidence for a deletion in the review or observation; Git is the
  undo path.

## Collapse duplication

- Search entrypoints and support files for the same decision stated in several
  places.
- Keep the full guidance at the lowest owner. Leave a short conditional route
  only where another skill genuinely crosses that boundary.
- Merge whole skills only in a dedicated review of their trigger surfaces.

## Re-check volatile facts

- Find dated claims, package versions, flags, APIs, service limits, hardware
  requirements, and current-product statements.
- Verify them against current official sources or change the guidance to check
  the installed environment at use time.
- Do not refresh stable concepts merely to create activity.

## Reduce routine context

- Flag entrypoints that approach the validator limit, repeat their support
  files, or contain command catalogs needed only occasionally.
- Move conditional depth behind descriptive links; then remove the duplicate
  prose from the entrypoint.
- Review descriptions for overlap using realistic neighboring requests, not
  keyword count alone.

Run `uv run scripts/engine/skill_metrics.py` and its `--dupes` view as useful
seeds, then verify every finding by reading the affected skill.

# Transcript retention

Transcripts are evidence, never prompt context.

- Keep a transcript while a queue flag, tentative observation, or ready
  observation points to it.
- A transcript becomes eligible for deletion when every linked observation is
  either rejected, or absorbed with its corresponding change landed.
- Unreferenced transcripts expire after the repository's retention window;
  pending evidence always wins over age.
- Run `uv run scripts/engine/prune_transcripts.py --dry-run` first and review
  every keep/delete reason.
- Use `--apply` only after the report identifies the intended files. Retention
  cleanup does not authorize deleting unrelated logs or application data.

---
name: learning-loop
description: Turn captured Robium experience into small, evidence-backed skill improvements.
---

# Learning loop

Capture is a lead, not knowledge. Promote it only when the evidence can improve
a future decision without injecting old conversations into new work.

## Capture without recall

- Hooks may queue corrections, failures, and transcript windows silently.
- Never insert queue items, observations, memories, or reminders into a new
  prompt. Read them only during an explicit consolidate, absorb, refine, or
  status task.
- Batch bookkeeping at a natural milestone. A command error or clean skill run
  is not automatically a reusable lesson.
- Keep project-specific facts in the application that owns them.

## Promote evidence

- Read the source transcript before turning a flag into an observation.
- Preserve what was expected, what actually happened, the evidence for the
  fix, and any dead ends that prevent repeating the mistake.
- Absorb only observations marked `ready`; uncertain material stays tentative.
- Deduplicate the finding before carrying it forward.
- Read [PROMOTION.md](PROMOTION.md) when deciding whether evidence is strong
  enough or which skill owns it.

## Change the least

- Put the finding in the lowest skill that owns the decision.
- Prefer correcting or replacing existing guidance over adding another rule.
- Keep the live entrypoint lean. Conditional commands, failures, tuning, and
  platform evidence belong in focused support files.
- Follow the `skill-author` quality bar and show the concrete diff with its
  evidence. Maintainer-authorized edits may land locally; unattended or
  unrequested absorption uses a branch and human-reviewed PR.
- Live skills are versionless and changelog-free. The legacy anchor/version
  delta applier is not the writer for the current skill format.

## Test according to risk

- Run the lightweight skill validator after an edit.
- Re-run an existing trigger or task check only when the changed guidance could
  affect it. Add a test only for a meaningful regression.
- For a contested edit, compare small alternatives against realistic requests
  and let a human choose. Do not preserve variants merely as ceremony.
- Read [TESTING.md](TESTING.md) for the optional eval format and safe task-check
  boundaries.

## Refine and retain

- Refinement starts with findings, not edits. Read [REFINING.md](REFINING.md)
  for the compact catalog review.
- Keep a transcript while a queue flag or nonterminal observation depends on
  it. Once linked observations are absorbed or rejected and the change has
  landed, read [RETENTION.md](RETENTION.md) and prune it deliberately.
- A status request may inspect queue size, ready observations, skill metrics,
  and transcript retention without changing anything.

## Done

- The future decision is clearer or safer with little added context.
- The observation points to evidence and its status reflects what landed.
- Relevant checks pass, and raw transcript evidence is kept only as long as it
  is still needed.

# Testing a skill change

Match the check to the risk. Most prose edits need the validator and manual
scenario review, not a new harness.

## Always

- Run `uv run skills/skill-author/scripts/validate_skills.py`.
- Read the result as a packaging check, not proof that the guidance is useful.
- For description, routing, or behavioral guidance changes, walk through a
  common request, the changed failure or choice, and the nearest request that
  should route elsewhere. Typos and mechanical link fixes do not need a
  ceremonial scenario review.

## Trigger checks

Keep `evals.yaml` only where selection is genuinely ambiguous:

```yaml
triggers:
  positive:
    - phrase: robot will not move to the navigation goal
  negative:
    - phrase: the Gazebo lidar topic is missing
      expect: gazebo
```

Run existing cases with `uv run scripts/engine/run_trigger_evals.py --skills
<name>`. If the semantic judge is unavailable, treat its lexical fallback as a
diagnostic, not a reason to stuff keywords into the description. Do not create
exhaustive synonym lists or assert exact description wording.

## Task checks

Use a task only for a reusable executable artifact or user-visible behavior:

```yaml
tasks:
  - name: example-runs
    command: uv run skills/example/examples/demo.py
    pass_criteria: "completed"
    timeout: 300
```

- `name`, `command`, and `pass_criteria` are required. Names are unique
  kebab-case; pass criteria are regular expressions.
- `app` may set a repository-relative working directory; `example` may point to
  the skill-relative artifact the task verifies.
- Paths cannot be absolute or escape their allowed root. Referenced examples
  and app directories must exist; apps cannot run from inside `skills/`.
  Timeouts must be positive.
- A task passes only when the command exits zero and its output matches.
- Commands are trusted repository content. Never build one from untrusted user
  input.

The validator and `scripts/engine/run_task_checks.py` share this schema.