name: add-lesson description: Add a new lesson learned to shared rules and sync to context files. version: 1.1.0 tags: [lessons, governance, rules] owner: orchestration status: active

Add Lesson Skill

Add a new lesson learned to the shared rules.

Overview

When you discover a bug, mistake, or useful pattern, use this skill to document it so all agents learn from it.

Usage

/add-lesson

Prerequisites

• Access to shared-rules/ and permission to run scripts/sync-rules.py.

Lesson Template

### YYYY-MM-DD - Brief Title

- **Issue**: What went wrong or was discovered
- **Root Cause**: Why it happened
- **Fix**: How it was fixed
- **Prevention**: Rule or check to prevent recurrence
- **Applies To**: all | claude | cursor | gemini
- **Files Changed**: List of affected files

Process

1. Gather information:

   • What was the issue?
   • What caused it?
   • How was it fixed?
   • How can we prevent it?

2. Add to lessons file:

   • Open shared-rules/lessons-learned.md
   • Add new entry at TOP of "Recent Lessons" section
   • Use the template format

3. Run sync:

   python scripts/sync-rules.py
   

4. Verify propagation:

   • Check CLAUDE.md updated
   • Check timestamp

Example

### 2026-01-22 - Task Tool Token Efficiency

- **Issue**: Spawning Claude workers via subprocess was expensive (~13k tokens overhead)
- **Root Cause**: Full context duplication to each subprocess
- **Fix**: Use native Task tool with context filtering
- **Prevention**: Always prefer Task tool over subprocess for Claude workers
- **Applies To**: claude
- **Files Changed**:
  - `.claude/skills/implement-task/SKILL.md`
  - `CLAUDE.md`

Categories

Lessons should be categorized by:

• all - Applies to all agents
• claude - Claude-specific
• cursor - Cursor-specific
• gemini - Gemini-specific

Archiving

After 30 days or when list gets long:

• Move old lessons to "Archived Lessons" section
• Keep for historical reference

Outputs

• Updated shared-rules/ content and synced context files (e.g. CLAUDE.md).

Error Handling

• If sync fails, do not proceed; resolve and rerun scripts/sync-rules.py.
• If lesson template is incomplete, request the missing fields before adding.

Related Skills

• /sync-rules - Sync shared rules into context files