# Team Learnings — Shared Knowledge Base Protocol

## What This Skill Does

Team Learnings is a real-time shared knowledge base that makes every agent smarter the moment any agent learns something. When one agent discovers a root cause, finds a better approach, or encounters a new failure mode, that knowledge is immediately written to a shared file that ALL agents read at session start.

**The principle:** If one agent learns it, every agent knows it. No agent should repeat a mistake that another agent already solved.

## How It Works

### Write Path (Immediate)
When any agent learns something — from an error, a success, operator feedback, or discovery — it writes the lesson to `ops/team-learnings.md` IMMEDIATELY. Not at end of day. Not at next flush. The moment the lesson crystallizes.

### Read Path (Session Start)
Every agent reads `ops/team-learnings.md` at session start, before doing any work. This ensures that lessons from overnight runs, other agents' sessions, and previous cycles are incorporated before the agent can repeat a known mistake.

### Categories

Lessons are organized by category:

| Category | What Goes Here |
|---|---|
| **Operational Rules** | Directives from the operator, behavioral rules, authority boundaries |
| **Technical Lessons** | Config gotchas, API quirks, infrastructure traps, port numbers |
| **Programming Lessons** | Code patterns that broke, syntax traps, schema mismatches |
| **Architecture Lessons** | System design insights, scaling considerations, integration patterns |
| **Detection Patterns** | New behavioral drift or conscience patterns discovered |
| **Tool Lessons** | Tool-specific knowledge, workarounds, best practices |

### Entry Format

```markdown
### {YYYY-MM-DD}
- **{Lesson title}.** {Concise description of the lesson, what happened, and what to do instead. Include specifics — numbers, file paths, config keys — not just vague principles.}
```

### Examples

**Good entries:**
```markdown
- **Default timeout was 120 seconds.** This killed every complex task. Found in openclaw.json under agents.defaults.timeoutSeconds. Removed it — now agents have no timeout.
- **Never raw-edit JSON.** Use json.load → modify → json.dump. Always. String replacement on structured data caused two gateway crashes in one day.
- **Check class names match between files.** BacktestEngine vs Backtester mismatch cost 20 minutes debugging. Always verify the import matches the actual class name.
```

**Bad entries:**
```markdown
- Be careful with configs.
- Sometimes things time out.
- JSON can be tricky.
```

## Integration with Wisdom

### Wisdom Writes Lessons
Wisdom writes to team learnings whenever:
- A new behavioral pattern is discovered
- A root cause is identified during error check-in
- An optimization is found during success check-in
- A conscience violation reveals a systemic issue

### Wisdom Monitors Compliance
Wisdom checks that:
1. Agents read team learnings at session start
2. Agents write lessons after errors (error check-in protocol)
3. Agents write lessons after successes (success check-in protocol)
4. No agent repeats a mistake already documented in team learnings

### Lesson Ignored Detection
If an agent makes a mistake that's already documented in team learnings, Wisdom flags it as LESSON_IGNORED — one of the most important detections, because it means the knowledge sharing system is failing.

## Agent Spawn Rules

When spawning any sub-agent or worker agent:
1. Include "Read ops/team-learnings.md first" in the task description
2. Include "When finished, report your results and any lessons learned"
3. This ensures every spawned agent benefits from accumulated knowledge

## Maintenance

- Team learnings file grows over time — that's correct
- Archive entries older than 90 days to `ops/team-learnings-archive.md` to keep the active file manageable
- Never delete lessons — they represent organizational memory
- Review monthly: are the lessons still accurate? Update any that have been superseded.

## The Rule

**Write lessons immediately. Not later. Now. The team gets smarter in real-time, not in batch.**
