Establish a "consolidation ritual" to keep skills & playbooks tight as learnings accumulate

[Hermsi1337]

Context

While reviewing #12 (the regular "learning harvest" from #10), @gandie raised a process concern worth tracking on its own, so it doesn't get lost in a merged PR thread.

One thought for meditation: Documenting sensible defaults and explaining mstudio behavior via pitfalls is a very good idea, but i am wondering how it will scale in the future. The error space of agent work is infinite and we can't document infinity ( yet ). Besides such regular learning harvests, maybe we need another ritual for consolidation to keep skills and playbooks tight? Just a thought to chew on i wanted to throw into the ring.

— PR #12 review

The concern

We currently have one ritual for growing the skills: harvesting verified learnings from real migrations into pitfalls.md and the playbooks (e.g. #10 → #12). That process is additive by design. Because the error space of agent work is effectively unbounded, a purely additive process makes the skills grow without bound — eventually they get long, repetitive, and harder for the agent to use well (and more expensive in context).

What's missing is the complementary ritual: consolidation — periodically pruning, deduplicating, and promoting accumulated pitfalls so the skills stay tight and high-signal.

Possible directions (to discuss — not a committed plan)

• Promote recurring pitfalls into defaults/principles. A pitfall that keeps recurring is really a missing sensible default. Once encoded as a default (like the "mirror the source engine" principle from feat(migrate): harvest migration-learnings from #10 #12), the individual pitfall entries can collapse into it.
• Deduplicate & merge overlapping entries — one canonical statement per trap.
• Prune stale/covered entries — things fixed upstream (CLI/API) or already covered by a default no longer need a standalone pitfall. (cf. the Migration learnings: Shared Hosting (Deployer/CI) → PHP Runtime App + MariaDB Container #10 triage that redirected CLI gaps to mittwald/cli issues instead of documenting workarounds.)
• Cadence & ownership — e.g. a consolidation pass every N harvests, or when a file crosses a size/signal threshold.
• Optimize for the right thing — keep skills tuned for agent success rate and context economy, not exhaustiveness.

Definition of done

This is a discussion/process item. "Done" means we have decided on:

1. whether we adopt a consolidation ritual at all,
2. its cadence/trigger, and
3. where it lives (e.g. a CONTRIBUTING note or a repeatable checklist)

— or have consciously decided not to.

---

Spun out of the #12 review so the thought doesn't get lost. 🤖 Filed with Claude Code.