Skip to content

foxrun-ai/foxrun / skillwright/skills/lesson

lesson

Verified

Add, promote, or prune a lesson in the tracker. A lesson is one rule the agents learned from a correction or a solved problem. Use for /lesson add, /lesson promote, /lesson prune, or when the person corrects how agents work, or a hard problem is solved and worth keeping.

FileKindSize
SKILL.mdskill md3.1 KB
replays/promote-retires-row.jsonconfig232 B
---
type: note
workspace: system
timestamp: 2026-10-26T14:20:00-04:00
name: lesson
description: "Add, promote, or prune a lesson in the tracker. A lesson is one rule the agents learned from a correction or a solved problem. Use for /lesson add, /lesson promote, /lesson prune, or when the person corrects how agents work, or a hard problem is solved and worth keeping."
kind: knowledge
argument-hint: "add | promote | prune | show [lesson id or words]"
---

# lesson

One skill for the lesson object. A lesson is one rule, in one line, that every agent reads at start.
Lessons live in the tracker so the start page shows them. Read the open ones from the `active_lessons` view.
A lesson is a waypoint, not a home. When a skill, contract line, or check can enforce it, promote it there.
When a lesson and a skill disagree, the skill wins, and the lesson becomes a fix to that skill.

## Find the tracker

Set `<ws>` to the workspace that owns the work. Do not route by the current folder alone.
Set `<tracker>` to `workspace_settings.<ws>.database` in `~/.foxrun/config/person.json`. If it is absent, use `~/.foxrun/data.db`.
In the commands below, `<work>` stands for this exact prefix:

```bash
python3 ~/.foxrun/work/work.py --workspace <ws> --db <tracker> --receipt-root ~/foxrun/<ws> --by <you>
```

Write `<you>` as your own agent name, never the runtime name.

## Steps

1. **Add.** When the person corrects how agents work, add the lesson in the same turn. When a hard problem is solved, add the one rule that would have saved the time.
   `<work> lesson-add --rule "<one line>" --source "<task id, comment:<id>, session, handoff, or file>" [--person-words "<their exact words>"] [--lesson-workspace <ws>|all] [--applies-to <seat>|all]`.
   Done when the command prints `ok lesson-add <id>`. A line that ends in `duplicate` names the lesson that already holds the rule; use it.
2. **Promote.** Find the skill, contract line, or check that should enforce the rule. Change it through its own owner: a skill through `skillify`, a contract through the person's yes. Then retire the lesson and point at the new home:
   `<work> lesson-update <lesson id> --status replaced --source "<path of the line that now enforces it>"`.
   Done when the enforcing line exists and the lesson row shows `replaced`.
3. **Prune.** Read the open lessons:
   `sqlite3 -readonly <tracker> "SELECT id,text,workspace,applies_to,created_on FROM active_lessons ORDER BY created_on"`.
   For each one, keep it, merge it, or retire it. Merge two lessons with `lesson-add --rule "<merged line>" --replaces <old id>`. Retire a stale one with `lesson-update <id> --status replaced --source "<why>"`. Done when each lesson you read has one of the three calls, and you listed them.
4. **Read it back.** Run `sqlite3 -readonly <tracker> "SELECT id,text,status,source FROM lessons WHERE id='<lesson id>'"`. Done when the row shows what you wrote.

## Gotchas

- Keep the rule to one line. Detail goes in the source the lesson points to.
- `--person-words` holds the exact words. Do not tidy them.
- Pruning only retires rows. It never deletes one.
- A lesson that keeps coming back is a sign the skill is wrong. Promote it.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall