2026-03-28 | 🗂️ Categorizing Daily Reflection Updates
🎯 The Problem
🔍 Every time the automation pipeline runs, it modifies files across the vault and logs those changes in the daily reflection note under a single Updates section.
🐛 Two issues surfaced. First, the social posting task was inserting a generic link to social-posting in the updates section, which pointed nowhere useful. Second, all update links were dumped into one flat list, making it impossible to tell at a glance whether a change came from image backfilling, internal linking, or social media posting.
💡 The Solution
🏷️ We introduced an UpdateCategory type that classifies each update link by the kind of automation that produced it.
📂 Three categories exist today: ImageUpdate, InternalLinkUpdate, and SocialPostUpdate. Each category maps to a descriptive sub-heading under the main Updates section.
🖼️ The Images sub-heading appears when blog post images are backfilled. The Internal Links sub-heading appears when navigation links are added between posts. The Social Posts sub-heading appears when content is shared on social media platforms.
🔧 What Changed
📝 The DailyUpdates module gained the UpdateCategory data type and a categorySubHeader function that maps each category to its emoji-prefixed heading.
🔄 The addUpdateLinks pure function now accepts a category parameter. It handles three cases: when no Updates section exists, it creates one with the appropriate sub-section; when the Updates section exists but the category sub-section is missing, it appends the sub-section; when the sub-section already exists, it inserts new links after the existing ones.
📢 The social posting fix was straightforward. We made runPostingPipeline return the list of ContentNotes that were actually posted successfully. Then autoPost maps each posted note to an UpdateLink with its real title and relative path. Instead of the meaningless social-posting link, each posted page now appears individually in the Social Posts sub-section.
🔌 RunScheduled passes ImageUpdate when logging image backfill changes and InternalLinkUpdate when logging navigation link changes.
📄 Example Output
📋 A daily reflection now shows updates like this. Under the Updates heading, you see an Images sub-heading with links to posts that got new images, then a Social Posts sub-heading with links to the specific pages that were shared on Twitter, Bluesky, or Mastodon. For instance, you might see Images containing a link to my-post, followed by Social Posts containing links to Cool Post and Some Book. Each link goes directly to the page that was modified, not to some generic automation label.
🧪 Testing
✅ We added fourteen new tests in a dedicated DailyUpdatesTest module.
🧪 Unit tests cover creating a new section with sub-headers, appending a sub-section to an existing Updates section, inserting links into an existing sub-section, skipping duplicates, handling empty link lists, mixing multiple categories in the same reflection, preserving content that follows the Updates section, and adding multiple links at once.
🎲 A property-based test verifies that addUpdateLinks never removes existing content lines from the reflection.
💾 Integration tests verify the full addUpdateLinksToReflection workflow: creating reflections, idempotency on repeated calls, and accumulating links from different categories into separate sub-sections on disk.
🏗️ All 278 tests pass, up from 260 before this change.
🔑 Key Design Decisions
🧩 We used a sum type rather than a plain string for categories. This gives us exhaustive pattern matching and compiler warnings if a new category is added without handling it everywhere.
📍 Sub-sections are inserted at the boundary of the Updates section, before the next level-two heading. This preserves the document structure even when other sections follow.
🔗 Link deduplication is done at the content level by checking if the wiki link target already appears anywhere in the reflection. This is category-agnostic, so a link cannot accidentally appear in two sub-sections.
📚 Book Recommendations
📖 Similar
- 📖 Domain Modeling Made Functional by Scott Wlaschin walks through encoding business domains as algebraic data types, which is exactly the pattern we used for UpdateCategory
- 📖 Haskell Programming from First Principles by Christopher Allen and Julie Moronuki covers sum types, pattern matching, and property-based testing from the ground up, all central to this change
↔️ Contrasting
- 📖 Working Effectively with Legacy Code by Michael Feathers approaches categorization and refactoring from the opposite direction, dealing with untyped or weakly typed systems rather than building with strong types from the start
🔗 Related
- 📖 The Art of Doing Science and Engineering by Richard Hamming explores how small structural improvements compound into significant productivity gains, much like how categorized sub-sections make daily reflections far more scannable