Lessons Consolidate
Purpose
This skill IS:
- A periodic curator of institutional knowledge in lessons.json
- A tool for detecting stale, overlapping, or contradictory lessons
- A way to keep the lessons collection healthy and useful
This skill IS NOT:
- For capturing new lessons (use ecosystem-manager for that)
- Automatically scheduled (invoke it periodically)
- A replacement for reading lessons (it maintains, doesn't apply them)
When to Use
- Monthly or every 10-15 sessions (whichever comes first)
- When lessons.json feels cluttered
- When you suspect lessons are outdated
- When you want to understand patterns across sessions
Modes
1. Analyze
Check the current state of lessons.json:
python .claude/scripts/consolidate_lessons.pyIdentifies:
- Stale lessons: Referenced concepts that no longer exist
- Overlapping lessons: Multiple lessons saying the same thing
- Contradictions: Lessons that conflict with each other
- Tag gaps: Important topics with no lessons
- Usage patterns: Which tags are over/under-represented
2. Consolidate
After analysis, with user approval:
- Archive stale lessons (don't delete - move to archived section)
- Merge overlapping lessons into single stronger lessons
- Flag contradictions for user resolution
- Suggest new lessons for uncovered areas
3. Report
Generate a health summary:
- Total lessons and trend
- Tag distribution
- Staleness assessment
- Recommendations for next actions
Guidelines
Good lessons are:
- Specific enough to act on
- General enough to apply to future situations
- Tagged with relevant categories
- Tied to a real experience (not hypothetical)
Boundary: Lessons vs Wiki
Use this boundary when bcos-wiki exists:
| Content | Owning surface | |---------|----------------| | Atomic, reusable rule for future agents or humans | lessons.json via ecosystem-manager | | Narrative incident explanation, timeline, causes, and follow-up context | Wiki post-mortem page-type | | Decision narrative, alternatives considered, and why a choice was made | Wiki decision-log page-type | | Step-by-step operational response | Wiki how-to or runbook page-type |
Lessons should stay short and actionable. Wiki pages can carry the richer story. If consolidation finds a lesson that is really a narrative, recommend moving the detail to /wiki create and keeping only the distilled lesson in lessons.json.
Cross-reference: docs/_bcos-framework/architecture/wiki-zone.md defines wiki page-type semantics and schema governance.
Remove or archive when:
- The lesson references something that no longer exists
- The lesson has been superseded by a better one
- The lesson is too vague to be useful
- The lesson contradicts current practice
References
- Lessons file:
.claude/quality/ecosystem/lessons.json - Schema:
.claude/quality/ecosystem/lessons-schema.md - Consolidation script:
.claude/scripts/consolidate_lessons.py