LESSONS

Shipyard Lessons Learned

[2026-04-08] Wiki 0.9.30 Full Sync

What Went Well

• Phase 1 audit (72 findings across 40+ pages) was extremely valuable — it provided a complete inventory that guided all subsequent work and prevented missed pages
• Transport Options pages had identical structures across SQL Server, PostgreSQL, SQLite, LiteDb, making parallel execution efficient with minimal per-transport deviation
• Clean break on Linq→Method rename (delete old files, no redirect stubs) was the right call — simpler and avoids maintenance burden
• Security caveats as visible warning blocks (> **Warning:** ...) are effective and hard to miss

Surprises / Discoveries

• Some pages were already partially updated in prior sessions, reducing Phase 4 work significantly (MessageHistory, MessageInterception, Admin, DashboardUi, DashboardConfiguration were largely correct)
• The Memory transport's "Delayed messages" feature claim was misleading — EnableDelayedProcessing is permanently false, so the code sample would silently fail
• Redis DelayedProcessingMonitorTime was documented as a direct property but the actual path is DelayedProcessingConfiguration.MonitorTime (nested object)
• Trace.md went from 4 lines to 100 lines — the original was essentially a placeholder, not documentation

Pitfalls to Avoid

• Grep verification patterns with -i flag can produce false positives (e.g., "Redis" matching "Disque" pattern)
• Builder agents sometimes skip writing SUMMARY.md files — verify artifacts exist during review
• Wiki rename operations on GitHub don't support redirects — plan for broken bookmarks when renaming pages

Process Improvements

• For large wiki syncs, having the source code + samples repo available is essential for verifying code samples compile
• Chronological migration guides (by version) are clearer for users upgrading from a specific version
• Running transport plans in parallel (6 at once) is highly efficient when pages don't share files

---